sun 

microsystems 



Sun Workstation, SunCore, SunCGI and the Sun logo 
are registered trademarks of Sun Microsystems, Incorporated. 

SunOS and SunView are trademarks of Sun Microsystems, Incorporated. 

UNIX® is a registered trademark of AT&T. 

All other products or services mentioned in this document are identified 
by the trademarks or service marks of their respective companies 
or organizations. 



Copyright © 1982, 1983, 1984, 1985, 1986, 1987, 1988, 1990 Sun Microsystems, Inc. - Printed in U.S.A. 

All rights reserved. No part of this work covered by copyright hereon may be reproduced in any form or by any 
means - graphic, electronic, or mechanical - including photocopying, recording, taping, or storage in an information 
retrieval system, without the prior written permission of the copyright owner. 

Restricted rights legend: use, duplication, or disclosure by the U.S. government is subject to restrictions set forth in 
subparagraph (c)(l)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and in 
similar clauses in the FAR and NASA FAR Supplement. 

The Sun Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun ack- 
nowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user inter- 
faces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, 
which license also covers Sun’s licensees. 

This product is protected by one or more of the following U.S. patents: 4,777,485 4,688,190 4,527,232 4,745,407 
4,679,014 4,435,792 4,719,569 4,550,368 in addition to foreign patents and applications pending. 




Contents 



Preface xxvii 

Chapter 1 Introduction 1 

What is SunView? 1 

History ., 2 

Release 3.0 2 

Release 3.2 2 

Release 3.4 2 

Release 3.5 2 

Release 4.0 2 

Release 4.1 3 

Code No Longer Supported 3 

Chapter 2 The SunView Model 5 

2.1. Objects 5 

Window Objects 7 

Other Visual Objects 7 

2.2. Examples of the use of Objects by Applications ...... 8 

2.3. Windows 12 

Frames 12 

Manipulating Frames Via Menus 14 

Subwindows 15 

2.4. Input: The Notifier 15 

Callback Style of Programming 15 

Why a Notification-Based System? 18 



Contents — Continued 



Relationship Between the Notifier, Objects, and the 

Application 18 

Calling the Notifier Directly 20 

Chapter 3 Interface Outline 21 

SunView Libraries 21 

Compiling SunView Programs 21 

Header Files 21 

Object Handles 22 

Attribute-based Functions 22 

Standard Functions 23 

Example of SunView-Style Programming 23 

Attribute List Size 23 

Reserved Namespaces 24 

Chapter 4 Using Windows 25 

4.1. Basic Routines 27 

Creating a Window 27 

Initiating Event Processing 27 

Modifying and Retrieving Window Attributes 27 

Destroying Windows 28 

4.2. Example 1 — hello jworld 29 

4.3. Example 2 — simple _panel 31 

Some Frame Attributes 32 

Panels 33 

Fonts 33 

Panel Items 33 

Notify Procedure 33 

Window Sizing — window_fit() 33 

Fitting Frames Around Subwindows 34 

4.4. Example 3 — lister 34 

4.5. Example A — filer 36 

Pop-ups 37 



- iv - 





Contents — Continued 



Pop-up Text Sub window 37 

Pop-up Property Sheet 38 

Invoking the ‘Props’ Menu Item 39 

WIN_SHOW 40 

Pop-up Confirmer 40 

window_loop 0 41 

Restrictions on Pop-Up Frames 42 

Controlling a Pop-up or Frame’s Shadowing 42 

4.6. Example 5 — image Jbrowserl 43 

Specifying Subwindow Size 43 

Default Subwindow Layout 44 

Explicit Subwindow Layout 44 

Specifying Subwindow Sizes and Positions 45 

Changing Subwindow Layout Dynamically 45 

The Rect Structure 45 

4.7. Example 6 — image _browser_2 46 

Row/Column Space 46 

4.8. Attribute Ordering 48 

Different Classes of Attributes 49 

The Panel Package 49 

4.9. File Descriptor Usage 50 

Counting File Descriptors 51 

File Descriptor Leakage 5 1 

Chapter 5 Canvases 53 

5.1 . Creating and Drawing into a Canvas 55 

5.2. Scrolling Canvases 57 

5.3. Canvas Model 58 

The Canvas 58 

5.4. Repainting 59 

Retained Canvases 59 

Non-Retained Canvases 59 

The Repaint Procedure 59 





Contents — Continued 



Retained vs. Non-Retained 60 

5.5. Tracking Changes in the Canvas Size 60 

Initializing a Canvas 60 

5.6. Automatic Sizing of the Canvas 62 

5.7. Handling Input in Canvases 63 

Default Input Mask 63 

Writing Your Own Event Procedure 63 

Translating Events from Canvas to Window Space 63 

Border Highlighting 64 

5.8. Color in Canvases 65 

Setting the Colormap Segment 65 

Color in Retained Canvases 65 

Color in Scrollable Canvases 65 

Chapter 6 Handling Input 67 

6.1. An Overview of the Input Environment 69 

How are events generated ? 69 

What does the Notifier do with these events ? 70 

How do windows determine which input they will receive? 70 

6.2. Events 70 

An event Procedure 70 

How Subwindows Handle Events 71 

6.3. A List of Events 71 

Keyboard Motions 75 

6.4. Classes of Events 76 

ASCII Events 76 

Locator Button Events 76 

Locator Motion Events 76 

Window Events 77 

Function Key Events 78 

Shift Key Events 79 

Semantic Events 79 

Other Events 79 

— vi- 





Contents — Continued 



6.5. Event Descriptors 80 

6.6. Controlling Input in a Window 80 

Input Focus 81 

Input Mask 81 

Determining which Window will Receive Input 82 

6.7. Enabling and Disabling Events 83 

Which Mask to Use 83 

Setting the Input Mask as a Whole 85 

Querying the Input Mask State 85 

6.8. Querying and Setting the Event State 86 

6.9. Releasing the Event Lock 87 

6.10. Reading Events Explicitly 87 

Chapter 7 Imaging Facilities: Pixwins 89 

7.1. What is a Pixwin? 91 

7.2. Accessing a Pixwin’ s Pixels 91 

Obtaining the Window’s Pixwin 91 

Write Routines 92 

Basic RasterOp Operations 92 

Other Raster Operations 92 

Text Routines 93 

Batching and Stenciling Routines 94 

Drawing Polygons 95 

Drawing Curved Shapes 95 

Drawing Lines 95 

Read and Copy Routines 96 

7.3. Rendering Speed 96 

Locking 97 

Batching 98 

Locking and Batching Interaction 100 

7.4. Clipping With Regions 100 

7.5. Color 101 

Introduction to Color 101 



- vii - 





Contents — Continued 



The Colormap 101 

Changing the Colormap 102 

Colormap Segments 102 

Background and Foreground 103 

Default Colormap Segment 103 

Changing Colors from the Command Line 103 

Sharing Colormap Segments 103 

Example: showcolor 104 

Manipulating the Colormap 105 

Cycling the Colormap 106 

Miscellaneous Utilities 107 

Using Color 107 

Cursors and Menus 107 

Is My Application Running on a Color Display? 108 

Simulating Grayscale on a Color Display 108 

Software Double Buffering 108 

Hardware Double-Buffering Ill 

7.6. Plane Groups and the cgf our Frame Buffer 1 13 

SunView and Plane Groups 1 14 

sunview and Plane Groups 1 15 

Chapter 8 Text Subwindows 117 

Summary Tables 117 

8.1. Text Subwindow Concepts 120 

Creating a Subwindow 120 

Attribute Order 120 

Determining a Character’s Position 120 

Getting a Text Selection 120 

Editing a Text Subwindow 120 

8.2. Loading a File 121 

Checking the Status of the Text Subwindow 121 

Textsw_status Value 121 

8.3. Writing to a Text Subwindow 122 

- viii - 




Contents — Continued 



Insertion Point 123 

Positioning to End of Text 123 

8.4. Reading from a Text Subwindow 123 

8.5. Editing the Contents of a Text Sub window 124 

Removing Characters 124 

Emulating an Editing Character 124 

Replacing Characters 125 

The Editing Log 126 

Which File is Being Edited? 126 

Interactions with the File System 126 

8.6. Saving Edits in a Subwindow 127 

Storing Edits 127 

Discarding Edits 127 

8.7. Setting the Contents of a Text Subwindow 128 

TEXTSW_FILE_CONTENTS 128 

TEXTSW_CONTENTS 128 

TEXTSW_INSERT_FROM_FILE 129 

8.8. Positioning the Text Displayed in a Text Sub window 129 

Screen Lines and File Lines 129 

Absolute Positioning 1 30 

Relative Positioning 1 30 

How Many Screen Lines are in the Subwindow? 131 

Which File Lines are Visible? 131 

Guaranteeing What is Visible 131 

Ensuring that the Insertion Point is Visible 131 

8.9. Finding and Matching a Pattern 132 

Matching a Span of Characters 1 32 

Matching a Specific Pattern 1 32 

8.10. Marking Positions 133 

8.11. Setting the Primary Selection 135 

8.12. Dealing with Multiple Views 135 

8.13. Notifications from a Text Subwindow 136 



— ix - 




Contents — Continued 



Chapter 9 Panels 139 

9.1. Introduction to Panels and Panel Items 145 

Message Items 145 

Button Items 145 

Choice Items 145 

Toggle Items 146 

Text Items 146 

Slider Items 146 

9.2. Basic Panel Routines 146 

Creating and Sizing Panels 146 

Creating and Positioning Panel Items 147 

Explicit Item Positioning 147 

Default Item Positioning 148 

Laying Out Components Within an Item 148 

Modifying Attributes 148 

Panel- Wide Item Attributes 150 

Retrieving Attributes 150 

Destroying Panel Items 151 

9.3. Using Scrollbars With Panels 152 

Creating Scrollbars 152 

Scrolling Panels Which Change Size 152 

Detaching Scrollbars from Panels 153 

9.4. Messages 154 

9.5. Buttons 154 

Button Selection 154 

Button Notification 154 

Button Image Creation Utility 155 

9.6. Choices 157 

Displaying Choice Items 157 

Choice Selection 158 

Choice Notification 159 

Choice Value 159 

Choice Menus 159 




Contents — Continued 



9.7. Toggles 163 

Displaying Toggles 163 

Toggle Selection 163 

Toggle Notification 163 

Toggle Value 163 

Toggle Menus 165 

PANEL_CHOICE_FONT 165 

9.8. Text 166 

Displaying Text Items 166 

Text Selection 167 

Text Notification 168 

Writing Your Own Notify Procedure 169 

Text Value 170 

Text Menus 171 

9.9. Sliders 172 

Displaying Sliders 172 

Slider Selection 172 

Slider Notification 172 

Slider Value 173 

9.10. Painting Panels and Individual Items 173 

9. 1 1 . Iterating Over a Panel’s Items 176 

9.12. Panel Item Client Data 176 

9.13. Event Handling 177 

Default Event Handling 177 

Writing Your Own Event Handler 177 

Translating Events from Panel to Window Space 181 

Chapter 10 Alerts 185 

10.1. Introduction to Alerts 185 

Uses of Alerts 186 

10.2. The Components of an Alert 186 

Alert Arrow 186 

Multiple-Line Text Message 186 

-xi- 




Contents — Continued 



Buttons 187 

Positioning 187 

Beeping 187 

10.3. alert_prompt ( ) 187 

10.4. Building an Alert 188 

Example 1 — Messages and Simple Buttons 188 

Yes and No Buttons 1 89 

Example 2 — Changing Fonts 191 

Example 3 — Using Triggers 192 

Chapter 11 TTY Subwindows 195 

11.1. Creating a TTY Sub window 1 97 

11.2. Driving a TTY Subwindow 197 

ttysw_input ( ) 197 

ttysw_output ( ) 198 

Example: tty Jo 198 

11.3. TTY Subwindow Escape Sequences 198 

Standard ANSI Escape Sequences 198 

Special Escape Sequences 199 

Example: tty Jo 199 

1 1.4. Reading and Writing to a TTY Subwindow 199 

1 1.5. The Program in the TTY Sub window 199 

TTY_PID 199 

Talking Directly to the TTY Sub window 200 

An Example 200 

Chapter 12 Menus 203 

12.1. Basic Menu Usage 206 

12.2. Components of Menus & Menu Items 210 

Menus 210 

Visual Components 210 

Generate Procedures 210 

Notify Procedures 210 

- xii - 




Contents — Continued 



Client Data 210 

Menu Items 210 

Menu Items 210 

Representation on the Screen 210 

Item Values 211 

Item Generate Procedures 2 1 1 

Item Action Procedures 211 

Client Data 211 

Item Margins 212 

12.3. Examples 212 

12.4. Item Creation Attributes 219 

12.5. Destroying Menus 220 

12.6. Searching for a Menu Item 221 

12.7. Callback Procedures 222 

Flow of Control in menu_show ( ) 222 

Generate Procedures 224 

Menu Item Generate Procedure 225 

Menu Generate Procedure 226 

Pull-right Generate Procedure 228 

Notify/Action Procedures 229 

12.8. Interaction with Previously Defined SunView Menus 230 

Using an Existing Menu as a Pull-right 230 

12.9. Initial and Default Selections 231 

12.10. User Customizable Attributes 232 

Chapter 13 Cursors 234 

13.1. Creating and Modifying Cursors 236 

13.2. Copying and Destroying Cursors 236 

13.3. Crosshairs 237 

13.4. Some Cursor Attributes 238 

Chapter 14 Icons 241 

14.1. Using Images Generated With iconedit 242 

- xiii - 





Contents — Continued 



14.2. Modifying the Icon’s Image 243 

14.3. Loading Icon Images At Run Time 244 

Chapter 15 Scrollbars 245 

15.1. Scrolling Model 247 

15.2. Scrollbar User Interface 249 

Types of Scrolling Motion 249 

Undoing a Scroll 249 

15.3. Creating, Destroying and Modifying Scrollbars 250 

15.4. Programmatic Scrolling 253 

SCROLL_NORMALIZE attribute 253 

Chapter 16 The Selection Service 255 

16.1. Getting the Primary Selection 256 

16.2. Setting the Primary Selection 256 

Chapter 17 The Notifier 257 

Header Files 257 

Related Documentation 257 

17.1. When to Use the Notifier 259 

17.2. Restrictions 259 

Don’t Call 259 

Don’t Catch 260 

17.3. Overview 261 

How the Notifier Works 261 

Client Handles 261 

Types of Interaction 26 1 

17.4. Event Handling 262 

Child Process Control Events 262 

“Reaping” Dead Processes 262 

Results from a Process 263 

Input-Pending Events (pipes) 264 

Example: Reading a Pipe 264 



- xiv- 





Contents — Continued 



Closing the Pipe 265 

Signal Events 265 

A signal () Replacement for Notifier Compatibility 265 

Example: Writing to a Pipe 266 

Asynchronous Event Handling 267 

Timeout Events 268 

Example: Periodic Feedback 268 

Polling 269 

Checking the Interval Timer 270 

Turning the Interval Timer Off 270 

17.5. Interposition 270 

How Interposition Works 270 

Monitoring a Frame’s State 271 

Example: Interposing on Open/Close 271 

Discarding the Default Action 273 

Interposing on Resize Events 273 

Example: resize_demo 273 

Modifying a Frame’s Destruction 273 

Destroy Events 274 

Checking 274 

Destruction 274 

A Typical Destroy Handler 274 

Example: Interposing a Client Destroy Handler 275 

17.6. Porting Programs to SunView 277 

Explicit Dispatching 277 

Implicit Dispatching 277 

Getting Out 278 

17.7. Error Handling 279 

Error Codes 279 

Handling Errors 279 

Debugging 280 

NOTIFY_ERROR_ABORT 280 

Stop in notif y__perror ( ) or fprintf(3S) 280 



- XV - 





Contents — Continued 



notify_dump 280 

Chapter 18 Attribute Utilities 281 

18.1. Character Unit Macros 281 

18.2. Creating Reusable Attribute Lists 282 

Default Attributes 283 

18.3. Maximum Attribute List Size 283 

Chapter 19 SunView Interface Summary 285 

Alert Tables 286 

Attributes 286 

Functions 288 

Canvas Tables 289 

Attributes 289 

Functions and Macros 290 

Cursor Tables 291 

Attributes 291 

Functions 293 

Data Types 294 

Help Tables 298 

Help Attributes 298 

Functions and Macros 298 

Icon Tables 299 

Attributes 299 

Functions and Macros 300 

Input Event Tables 301 

Event Codes 301 

Event Descriptors 304 

Input-Related Window Attributes 305 

Menu Tables 306 

Attributes 306 

Item Attributes 310 

Functions 312 



- xvi - 





Contents — Continued 



Notifier Functions Table 314 

Notifier Functions Table 3 14 

Panel Tables 317 

Attributes 317 

Generic Panel Item Attributes 318 

Choice and Toggle Item Attributes 320 

Slider Item Attributes 322 

Text Item Attributes 323 

Functions and Macros 324 

Pixwin Tables 327 

Pixwin Drawing Functions and Macros Table 327 

Pixwin Color Manipulation Functions Table 33 1 

Attributes 333 

Functions and Macros 336 

Text Subwindow Tables 337 

Attributes 337 

Textsw_action Attributes 341 

Textsw_status Values 342 

Functions 343 

TTY Subwindow Tables 347 

Attributes 347 

Functions 347 

Special Escape Sequences 349 

Window Tables 351 

Attributes 35 1 

Frame Attributes 354 

Functions and Macros 356 

Command Line Frame Arguments 358 

Appendix A Example Programs 359 

Source Available 359 

A.l. filer 359 

A.2. image browser _1 370 

- xvii - 





Contents — Continued 



A.3. image_browser_2 374 

A.4. tty Jo 379 

A.5. fontjnenu 382 

A.6. resizedemo 389 

A.7. detool 394 

A.8. typein 400 

A. 9. Programs that Manipulate Color 404 

coloredit 404 

animatecolor 409 

A. 10. Two gfx subwindow-based programs converted to use 

SunView 416 

bounce 416 

spheres 42 1 

Appendix B Sun User Interface Conventions 427 

B. l. Program Names 427 

B.2. Frame Headers 427 

B.3. Menus 427 

Capitalization 427 

Menus Showing Button Modifiers 428 

Interaction with Standard Menus 428 

Enable/Disable Menu Items 428 

Multi-Column Menus 428 

B.4. Panels 428 

Buttons 429 

List of Non-Exclusive Choices 429 

List of Exclusive Choices 429 

Binary Choices 430 

Text Items 430 

Allocation of Function Between Buttons and Menus 430 

B.5. Mouse Button Usage 431 

Allocation of Function Between Mouse Buttons 431 

Using Mouse Buttons for Accelerators 431 

- xviii - 





Contents — Continued 



B.6. Cursors 431 

B. 7. Icons 431 

Appendix C Converting SunWindows Programs to SunView 433 

C. l. Converting Tools 434 

General Comments 434 

Programming Style Changes 434 

Object typedefs 434 

Attribute Value Interface 434 

New Objects 435 

Canvas Subwindows 435 

Text Subwindows 435 

Scrollbars 435 

Objects in Common between SunView and SunWindows 436 

Cursors 436 

Icons 436 

Menus 437 

Input Events 437 

Setting up Input Event Handling 438 

Sigwinch Handling 438 

Windows 438 

Panels 438 

Signals 439 

Prompts 439 

C.2. Converting Gfxsubwindow-Based Code 441 

Basic Steps 441 

Replacing Tool Interaction 441 

Styles of Damage Checking 44 1 

Either the Notifier Takes Over 441 

Or Your Code Stays in Control 442 

Handling Damage 442 

The gfxsw Structure 442 

Finishing Up 443 

- xix - 





Contents — Continued 



Miscellaneous 443 

Two Examples 444 

Index 445 



- XX - 





Tables 



Table 3-1 Reserved Prefixes 24 

Table 4-1 Window Usage Examples 25 

Table 4-2 Window Row/Column Geometry Attributes 46 

Table 4-3 SunView File Descriptor Usage 50 

Table 6-1 Event Codes 72 

Table 6-2 Keyboard Motions and Accelerators 75 

Table 6-3 Event Descriptors 80 

Table 6-4 Attributes Used to Set Window Input Masks 83 

Table 6-5 Macros to Get the Event State 86 

Table 6-6 Macros to Set the Event State 87 

Table 7-1 Sample Colormap to Isolate Planes 109 

Table 7-2 Pixwin-Level set Attributes 113 

Table 7-3 Pixwin-Level get Attributes 113 

Table 8-1 Textsw_status Values 122 

Table 8-2 Text sw_act ion Attributes 137 

Table 9-1 Text Item Notification 168 

Table 9-2 Return Values for Text Item Notify Procedures 169 

Table 9-3 Panel Event Handling Attributes 177 

Table 9-4 Panel Action Functions 179 



Tables — Continued 



Table 12-1 Attributes to Add Pre-Existing Menu Items 217 

Table 12-2 Menu Item Creation Attributes 219 

Table 12-3 Menu Attributes Recognized by menu_find() 221 

Table 12-4 User Customizable Menu Attributes 232 

Table 15-1 Scrolling Motions 249 

Table 18-1 Example uses of the ATTR_ROW ( ) and ATTR_COL ( ) 

macros 281 

Table 18-2 Example uses of the ATTR_ROWS() and 

ATTR_COLS ( ) macros 282 

Table 19-1 Alert Attributes 286 

Table 19-2 Alert Functions 288 

Table 19-3 Canvas Attributes 289 

Table 19-4 Canvas Functions and Macros 290 

Table 19-5 Cursor Attributes 291 

Table 19-6 Cursor Functions 293 

Table 19-7 Data Types 294 

Table 19-8 Help Attributes 298 

Table 19-9 Help Functions and Macros 298 

Table 19-10 Icon Attributes 299 

Table 19-11 Icon Functions and Macros 300 

Table 19-12 Event Codes 301 

Table 19-13 Event Descriptors 304 

Table 19-14 Input-Related Window Attributes 305 

Table 19-15 Menu Attributes 306 

Table 19-16 Menu Item Attributes 310 

Table 19-17 Menu Functions 312 

Table 19-18 Notifier Functions 314 

Table 19-19 Panel Attributes 317 

Table 19-20 Generic Panel Item Attributes 318 

Table 19-21 Choice and Toggle Item Attributes 320 

Table 19-22 Slider Item Attributes 322 



- xxii - 





Tables — Continued 



Table 19-23 Text Item Attributes 323 

Table 19-24 Panel Functions and Macros 324 

Table 19-25 Pixwin Drawing Functions and Macros 327 

Table 19-26 Pixwin Color Manipulation Functions 331 

Table 19-27 Scrollbar Attributes 333 

Table 19-28 Scrollbar Functions 336 

Table 19-29 Text Subwindow Attributes 337 

Table 19-30 Text sw_act ion Attributes 341 

Table 19-31 Text sw_status Values 342 

Table 19-32 Text Subwindow Functions 343 

Table 19-33 TTY Subwindow Attributes 347 

Table 19-34 TTY Sub window Functions 347 

Table 19-35 TTY Subwindow Special Escape Sequences 349 

Table 19-36 Window Attributes 351 

Table 19-37 Frame Attributes 354 

Table 19-38 Window Functions and Macros 356 

Table 19-39 Command Line Frame Arguments 358 

Table C-l SunWindows => SunView Equivalences 440 



- xxiii - 







Figures 



Figure 2-1 SunView Objects 6 

Figure 2-2 Mailtool 8 

Figure 2-3 iconedit 9 

Figure 2-4 mailtool-buttons 10 

Figure 2-5 mailtool-menus 1 1 

Figure 2-6 A subframe 12 

Figure 2-7 Structure of iconedit 13 

Figure 2-8 Structure of mailtool 13 

Figure 2-9 Base frame menu 14 

Figure 2-10 Subframe menu 14 

Figure 2-11 Flow of Control in a Conventional Program 16 

Figure 2-12 Flow of Control in a Notifier-based Program 17 

Figure 2-13 Flow of Input Events in iconedit, a SunView 

Application 19 

Figure 4-1 Hello World Window 30 

Figure 4-2 Hello World Panel 32 

Figure 4-3 lister 34 

Figure 4-4 filer 36 

Figure 4-5 A Pop-up Text Subwindow 37 

Figure 4-6 A Non-blocking Pop-up 39 

Figure 4-7 Pop-up Confirmer 41 

Figure 4-8 image browser ] 43 

Figure 4-9 image _browser_2 46 



- xxv - 




Figures — Continued 



Figure 5-1 Canvas Geometry 58 

Figure 6-1 Input Events 69 

Figure 8-1 Text Subwindow 117 

Figure 9-1 Associating a Menu With a Button 156 

Figure 9-2 A Dial-Like Choice Item 162 

Figure 9-3 iconedit’s Drawing Mode Choice Item 162 

Figure 9-4 A Toggle Item 164 

Figure 9-5 A Text Menu 171 

Figure 9-6 A Typical Slider 173 

Figure 9-7 Image Browser Subframe Using 

pane l_window_e vent ( ) 182 

Figure 10-1 An Alert 186 

Figure 10-2 A Simple Alert 188 

Figure 10-3 A YES/NO Alert 190 

Figure 10-4 An Alert with Boldface Message Strings 191 

Figure 10-5 An Alert Using Triggers and Events 193 

Figure 12-1 Layout of a Menu Item 212 

Figure 12-2 Display Stage of Menu Processing 223 

Figure 12-3 Notification Stage of Menu Processing 224 

Figure 15-1 Scrolling Model 248 

Figure 15-2 Attributes Controlling Scrollbar Appearance 252 

Figure 15-3 Scrollbar Placement Attributes 252 

Figure 17-1 Overview of Notification 261 

Figure 17-2 Flow of Control in Interposition 271 



- xxvi - 





Preface 



Audience for this Manual 



How this Manual is 
Structured 

Tutorial 



User’s Guide 



Reference 



SunView' 1.80 Update 



This manual is addressed to anyone who is interested in writing SunView pro- 
grams. It assumes that the reader understands the C programming language. 
Before you begin to write your own programs, read the SunView User's Guide 
and spend some time using the SunView environment to become familiar with 
the tools and demonstration programs provided with SunView. 1 

This manual is a combination Tutorial, User’s Guide, and Reference. In addi- 
tion, a companion volume describes the additions to SunView 1.80. 

Chapter 4, Using Windows , serves as a tutorial introduction to SunView. As you 
read and type in and finally modify its examples, you will be writing simple Sun- 
View programs in the proverbial “10 minutes to SunView” time frame. You can 
then read the later chapters when you need to incorporate the features they 
describe into your programs. 

This entire manual is the user’s guide. Start at the beginning, keep reading, and 
you will understand the SunView model, how SunView programs work, and how 
to create and use all the different SunView objects in your own window pro- 
grams. 

Chapter 19, SunView Interface Summary, lists all the attributes of the different 
SunView objects and packages, and the functions and macros to operate on them. 
Because of the nature of SunView and its use of an attribute value interface, it 
uses a few simple calls with many attributes for them. Hence in practice this is 
all the reference section you will need on a day-to-day basis. 

New material concerning the features added to SunView 1 .80 is published under 
separate cover, as SunView 1.80 Update, part number 800-4738-01. This 
material is collected in one place to make it easier for those of you who are 
already familiar with SunView, and therefore only want to examine the new 
features. 



1 These tools and demonstration programs are optional software. They may not be installed on your system. 
Consult Installing SunOS 4.1 for more details. 
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Preface — Continued, 



Further Reading 



Format of Chapters 



Lists, Summaries, and the Index 



This manual does not teach you how the Sun View window system itself works, 
only how to make working SunView applications. The former is covered, along 
with many low-level, esoteric, and complex details, in the SunView System 
Programmer’ s Guide. 

The chapters which explain the various SunView packages have a common for- 
mat. Each chapter’s first page usually mentions 

□ what the package does 

□ existing SunView programs you can run to see the package in action 

□ header files you must include to use the package 

□ which are the “summary tables” for the package in the Chapter 19, SunView 
Interface Summary. 



The second page of most of the chapters on packages has a list of the attributes 
and functions the package provides. This information doesn’t tell you what you 
need to know to use the package; rather, it is intended to give you a feel for what 
you can do with the package. When you are more familiar with a package, you 
can go straight to its summary tables in Chapter 19 to quickly find out how to use 
some attribute or function. However , there may be tricks or nuances involved in 
using the package which are only covered in the chapters. You should consult 
the Index before using any attribute or function that you are not familiar with. 
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Introduction 



What is SunView? 



SunView (Sun Visual/Integrated Environment for Workstations) is a user- 
interface toolkit to support interactive, graphics-based applications running 
within windows. It consists of two major areas of functionality: building blocks 
for output, and a run-time system for managing input. The building blocks 
include four types of windows: 

□ canvases on which programs can draw, 

o text subwindows with built in editing capabilities, 

□ panels containing items such as buttons, choice items, and analog sliders, 

□ tty subwindows in which programs can be run. 

Canvases, text subwindows, and panels can be scrolled. 

These windows are arranged as subwindows within frames, which are themselves 
windows. Frames can be transitory or permanent. 

Transient interactions with the user can also take place in menus which can 
“pop-up” anywhere on the screen, and in alerts. 

The run-time system is based on a central Notifier in each application which dis- 
tributes input to the appropriate window, and a window manager which manages 
overlapping windows, distributing to the appropriate application. 

The exchange of data between applications running in separate windows (in the 
same or separate processes) is facilitated by a Selection Service. 

The Sun implementations of graphics standards — CGI, GKS — include exten- 
sions to run within windows. See the SunCGI Reference Manual, and the 
SunGKS manuals, respectively, for more information. 
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2 Sun View Programmer’s Guide 



History 

Release 3.0 SunView first appeared in SunOS Release 3.0. It is an extension and refinement 

of SunWindows 2.0, containing many enhancements, bug fixes and new facilities 
not present in SunWindows. SunView is upward compatible with SunWindows 
— applications originally written under 2.0 can be recompiled and run under 
SunView. 

In Release 3.0, these changes were reflected in a new organization for the Sun- 
View documentation. The material on Pixrects from the 2.0 SunWindows Refer- 
ence Manual was broken out into a separate document, the Pixrect Reference 
Manual. Two new documents were introduced, the SunView Programmer’s 
Guide and the SunView System Programmer’s Guide. 

The basic SunView interface, intended to meet the needs of simple and 
moderately complex applications, is documented here. This basic interface cov- 
ers the functionality of the SunWindows window and tool layers. 

The companion to this document is the SunView System Programmer’s Guide. 

Its contents are a combination of new and old material. Several of its chapters 
document new facilities such as the Notifier, the Selection Service and the 
Defaults Package. Also included is material from the old SunWindows Reference 
Manual which is of interest to implementors of window managers and other 
advanced applications, such as the window manager routines. 

Release 3.2 Many bug fixes and performance improvements were made to SunView for 

Release 3.2. This guide was extensively revised and added to for Release 3.2. 

Release 3.4 Further bug fixes and enhancements came out with Release 3.4. These were 

documented in the Release 3.4 Manual. 

Release 3.5 Release 3.5 brought support for hardware double -buffering under SunView and 

pixrects. 

Release 4.0 Release 4.0 brings major enhancements to the SunView user interface — ‘Search 

and Replace’ in text subwindows, shadowed frames, ‘Props’ frame menu item, 
keyboard control of the caret, etc. — without involving major changes to its pro- 
grammatic interface. For example, when programs that use text subwindows are 
recompiled, their users will be able to use the new ‘Select Marked Text' pop-up 
frame. The alerts package is a new package for presenting information to the 
user and allowing him/her to make choices based on it. 

This guide was revised and reprinted again for 4.0. The major changes are the 
addition of a new Alerts chapter and lists of attributes and functions at the begin- 
ning of some chapters as well as in the SunView Interface Summary chapter and 
Index. 
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Release 4.1 Release 4.1 of SunOS is accompanied by Sunview 1.80, whose major features 

are: 

o an online help mechanism*, allowing application developers to provide 
Spot Help for their users, 

□ programmable alarms* for dramatically notifying users, 

□ keyboard support 

- type 4 keyboard 

- upgraded description of the . textswrc file* 
o enhanced color capabilities 

- colored panel items*, 

- support for 24-bit true color*, 

□ changes to the defaults database 

o several user changes, 

□ various bug fixes*. 

Code No Longer Supported Do not use define_icon_from_image or 

DEFlNE_CURSOR_FROM_lMAGE as these macros may not be supported in 
future releases. Instead, use icon_create ( ) and cursor_create ( ) to 
create the icon or cursor at runtime. icon_create ( ) is described in Chapter 
14, Icons. cursor_create( ) is described in Chapter 13, Cursors. 

The old SunWindows stacking menu package has been supplanted by the Sun- 
View walking menu package, described in Chapter 12 of this document. You 
should convert your applications to use the menu package, as the old package 
may not be included in future releases. 

The new alerts package, described in Chapter 10, replaces use of the old (undo- 
cumented) menu prompt ( ) routine in situations where programs want to 
force the user to acknowledge a message or make a choice. Alerts are more flexi- 
ble and easy-to-use than menu_prompt ( ) , and we strongly encourage you to 
convert to them. Again, the old package may not be included in future releases. 



1 * See the SuriView 1.80 Update. This new publication, part number 800-4738-10, is an appendix to the 
SunView Programmer’ s Guide offering a more a detailed description of these features. It contains the update 
information for both the SunView Systems Programmer’s Guide as well. 
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The SunView Model 



This chapter introduces the conceptual model presented by SunView, covering 
such basic concepts as objects , windows and the Notifier. 

It is important that you understand the material in this chapter before you begin 
to write SunView applications. 

2.1. Objects SunView is an object-oriented system. Think of SunView objects as visual 

building blocks which you use to assemble the user interface to your application. 
Different types of objects are provided, each with its particular properties; you 
employ whatever type of object you need for the task at hand. 

The most important class of SunView objects are windows. Not all objects are 
windows, however. Other visual objects include cursors, icons, menus and 
scrollbars. 

Technically, an object is a software entity presenting a functional interface. The 
implementation of the object is not exposed; you manipulate an object by passing 
its unique identifier, or handle, to its associated functions. The style of program- 
matic interface resulting from this object-oriented approach is outlined in this 
Chapter. 

Figure 2-1 illustrates the different types and classes of SunView objects: 
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Figure 2-1 SunView Objects 




The different types of objects are shown in normal font; the classes to which the 
objects belong are labeled in italics — Subwindow, Window, and Object. 

Each object type is described briefly on the next page. 
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Window Objects 



Other Visual Objects 



Window objects include frames and subwindows . Frames contain non- 
overlapping subwindows 2 within their borders. Currently, there are four types of 
subwindows provided by SunView: 

□ Panel Subwindow — A subwindow containing panel items. 

□ Text Subwindow — A subwindow containing text. 

□ Canvas Subwindow — A subwindow into which programs can draw. 

□ TTY Subwindow — a terminal emulator, in which commands can be given 
and programs executed. 

The distinctions between frames and subwindows are explained in more detail in 
Section 2.3, Windows, later in this chapter. 

The other types of objects, like windows, are displayed on the screen, but they 
differ from windows in that they are less general and more tailored to their 
specific function. They include: 

□ Panel Item — A component of a panel that facilitates a particular type of 
interaction between the user and the application. Panel items can be moved, 
displayed or undisplayed under program control. There are several 
predefined types of items, including buttons, message items, choice items, 
text items and sliders. 

□ Scrollbar — An object attached to and displayed within a subwindow 
through which a user can control which portion of the subwindow’s contents 
are displayed. Both vertical and horizontal scrollbars can be attached to 
panels and canvases. Text subwindows contain vertical scrollbars by default 
(they cannot contain horizontal scrollbars). 

□ Menu — An object through which a user makes choices and issues com- 
mands. By convention in SunView, menus pop up when the user presses the 
right mouse button. Like windows, menus appear on the screen when 
needed, and disappear when they have served their purpose. Menus, how- 
ever, differ from windows in several ways. First, they are more ephemeral 
— a menu only remains on the screen as long as the menu button remains 
depressed, 3 in contrast to a window, which remains on the screen until the 
user indicates he is done or the controlling program explicitly undisplays it. 
Second, menus are less flexible than windows; they are designed specifically 
to allow the user to choose from among a list of actions. 



2 It is SunView’s window layout policy that enforces non-overlapping subwindows, not some limitation of 
the system. If you access the window system at a very low level, subwindows can overlap successfully. 

3 The one exception is in the case of stay-up menus, which will appear when you click the RIGHT mouse 
button and disappear when you click it again. 
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□ Alert — a box on the screen which informs the user of some condition. It 
has one or more buttons which the user can push to dismiss the alert or 
choose a means of continuing. Like menus, alerts are ephemeral — they 
disappear as soon as the user pushes a button or otherwise dismisses the 
alert. Visually, they resemble simple panels containing only images, mes- 
sages, and buttons. 

□ Pointer — The object indicating the mouse location on the screen. 

□ Icon — a small (usually 64 x 64 pixel) image representing the application. 

The next section gives some examples showing how typical applications make 

use of SunView objects in their user interface. 

2.2. Examples of the use of 
Objects by 
Applications 

Figure 2-2 



Figure 2-2 illustrates the mailtool(l), which uses SunView objects to provide 
a mouse-oriented interface to the SunOS mail(l) program: 

Mailtool 
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Mailtool consists of a frame containing three subwindows: a text subwindow in 
which the message headers are displayed, a panel containing various panel items 
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(mostly buttons) through which the user can give commands to mail, and a text 
subwindow which displays the current message. An additional text subwindow 
and panel (shown in the figure) appear when you press the reply or compose but- 
tons. 

The text subwindows contain scrollbars, allowing the user to bring more infor- 
mation into view. 

Figure 2-3 illustrates iconedit(l), a simple bitmap editor for generating 
images to be used by Sun View applications: 

Figure 2-3 iconedit 
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iconedit consists of a frame and five subwindows. From upper left to lower 
right they are: 

□ a panel containing instructions on how to use the mouse; 

□ a small panel for short messages; 

□ a canvas for drawing the image; 

□ a panel containing various items for issuing commands and setting options 
such as the size of the image being drawn, the drawing mode, etc; 

□ A small canvas for viewing the icon or cursor actual size. 
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None of these sub windows may be scrolled. 

In Figure 2-4, the user has pushed the New Mail button, and the program brings 
up a hour glass cursor (in the upper right of the text subwindow) to denote that it 
is retrieving mail: 

Figure 2-4 mailtool-buttons 
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Message- Id: <8710201000 . AA02077@snai 1 .sun.com> 

From: root@sun.com 
Subject: Tech Mail 
Apparent! y-To : tech-list 
Status: RO 

I Sun Tech Mail for Tue Oct 20 03:00:04 PDT 1987 



Requests to receive tech mail should be sent to aliases@sun, 
* Items you wish to post to tech should be sent to techSsun. 



{ Print )j§ll|l§ 
[ Mi sc ][ Done ] 



Today's Topics: 



mh wizards, anyone? 
console window problem 



Date: Mon, 19 Oct 87 14:54:11 PDT 
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In Figure 2-5, the user has pressed the mouse button over the Folder panel button 
in the panel: 

Figure 2-5 mailtool-menus 
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Received: by snai1.sun.com (4 .0 /SMI-3 2) 

id AA02077 , Tue, 20 Oct 87 03 00 09 PD7 
Date: Tue, 20 Oct 87 03:08:08 POT 
Message-Id : <8710201000 AA02077@snai 1 .sun.com> 

From, root8sun.com 
Subject: Tech Mail 
Apparently-To : tech-list 
Status: RO 

Sun Tech Mail for Tue Oct 20 03:00:04 PDT 1987 

**• Requests to receive tech mail should be sent to aliasesdsun. 
**** Items you wish to post to tech should bs sent to techSsun. 

Today 's Topics : 



mh wizards, anyone? 
console window problem 



Date Mon, IS Oct 87 14:54:11 POT 
From ncwicki8speed (Bill Nowick i) 

Subject mh wizards, anyone? 

I have hea'-d that a feature I added to seo(inail for 4.0 causes mh 
to break I don't use mh, so could someone who knows uhat it is 
doing please get in touch with me? I have a feeling it is using the -t 



mailtool has displayed a pop-up menu showing names of files which the user 
can insert into the text item File: by selecting a file. The purpose of this menu is 
to keep a current record of the mailfiles that the user has. 
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2.3. Windows 



Frames 



There are two basic classes of windows in SunView: overlapping frames, which 
contain non-overlapping subwindows. This section describes the distinction 
between the two. 



A frame is not useful in itself — its purpose is to bring subwindows of different 
types together into a common framework so they can be operated on as a unit. A 
frame is said to own the subwindows it contains. 

Frames may also own other frames. Thus the basic SunView structure is a 
hierarchy of windows. It could also be viewed as a tree of windows in which the 
non-leaf nodes are frames and the leaf nodes are subwindows. 

The frame at the top of the hierarchy will be referred to in this document as the 
base frame ; other frames will be referred to as subframes . 4 Subframes are typi- 
cally used to implement pop-ups, which perform auxiliary functions such as 
allowing the user to set options, or displaying help text. 5 

Note that subframes cannot be iconified, that is, they cannot be collapsed onto an 
icon. 

iconedit uses a pop-up for browsing images. When the user presses the but- 
ton labeled Browse, iconedit displays a pop-up which consists of a subframe 
containing a single panel subwindow. 

Figure 2-6 illustrates iconedit with its pop-up displayed. 



Figure 2-6 A subframe 




4 Note that while an application will usually be implemented as a single base frame (and its subwindows and 
subframes), it could well include several base frames. 

5 For details on pop-ups, see Section 4.5.1, Pop-ups, in Chapter 4, Using Windows. 
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Manipulating Frames Via Frames may be manipulated programmatically by setting the frame’s attributes, 

Menus as described in Chapter 4, Using Windows . Each frame also has a menu which 

allows the user to manipulate the frame directly. The frame menu is invoked by 
pressing the RIGHT mouse button on the exposed parts of the frame, which 
include the double lines surrounding the subwindows and the black frame header 
which usually appears at the top of the frame. 

The menus for base frames and subframes differ slightly, as you can see from 
Figure 2-9 and Figure 2-10. 

The first window shows the base frame menu; the second window shows the sub- 
frame menu; 

Figure 2-9 Base frame menu 




Figure 2-10 Subframe menu 




Both menus contain the ‘Move’, ‘Resize’, ‘Front’, ‘Back’, and ‘Redisplay’ com- 
mands. ‘Move’ allows the user to change the frame’s location. ‘Resize’ allows 




Revision A, of March 27, 1990 






Chapter 2 — The SunView Model 1 5 



him or her to change the window’s width and height. ‘Front’ causes the frame to 
move in front of the other windows, becoming fully visible on the “surface” of 
the screen, while ‘Back’ does the opposite, moving the frame behind any other 
windows occupying the same portion of the screen. ‘Redisplay’ simply causes 
the window to be displayed again. 

When the user is finished working with a base frame he may want to destroy it 
for good, in which case he would choose ‘Quit’. Or he may want to ‘Close’ the 
frame, with the anticipation of opening it later and continuing work where he left 
off. A base frame in its closed state is represented on the screen as a small (usu- 
ally 64 by 64 pixel) icon. The icon is typically a picture indicating the function 
of the underlying application. 

Subframes may not be closed into icons; when the user finishes with a subframe, 
he simply chooses Done from the menu. While not destroying the subframe, this 
causes it to disappear from the screen. 

Subwindows Subwindows differ from frames in several basic ways. Subwindows never exist 

independently. They are always owned by a frame, and may not themselves own 
subwindows or subframes. While frames can be moved freely around the screen, 
subwindows are constrained to fit within the borders of the frame to which they 
belong. Also in contrast to frames, subwindows are tiled — they may not over- 
lap each other within their frame. Within these constraints (which are enforced 
by a run-time boundary manager ) subwindows may be moved and resized by 
either a program or a user. 

So far this chapter has discussed the static aspects of the SunView model. The 
section below outlines the system's model from a dynamic point of view. 

2.4. Input: The Notifier SunView is a notification-based system. The Notifier acts as the controlling 

entity within a user process, reading UNIX input from the kernel, and formatting 
it into higher-level events, which it distributes to the different SunView objects. 6 

Callback Style of Programming In the conventional style of interactive programming, the main control loop 

resides in the application. An editor, for example, will read a character, take 
some action based on the character, then read the next character, and so on. 

When a character is received that represents the user’s request to quit, the pro- 
gram exits. Figure 2-11 illustrates this approach: 



6 SunView events are in a form which you can easily use: an ascii key has been pressed, a mouse button has 
been pressed or released, the mouse has moved, the mouse has entered or exited a window, etc. Events are 
described in detail in in Chapter 6, Handling Input. 
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Figure 2-11 Flow of Control in a Conventional Program 



start 




end 



Notification-based systems invert this “straight line” control structure. The main 
control loop resides in the Notifier, not the application. The Notifier reads events 
and notifies, or calls out to, various procedures which the application has previ- 
ously registered with the Notifier. These procedures are called notify procs or 
callback procs. This control structure is shown in Figure 2-12. 
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Figure 2-12 Flow' of Control in a Notifier-based Program 
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Why a Notification-Based 
System? 



Relationship Between the 
Notifier, Objects, and the 
Application 



For programmers who are not used to it, this callback style of programming takes 
some getting used to. Its big advantage is that it takes over the burden of manag- 
ing a complex, event-driven environment. In SunView, an application typically 
has many objects. In the absence of a centralized notifier, each application must 
be responsible for detecting and dispatching events to all the objects in the pro- 
cess. With a centralized Notifier, each component of an application receives only 
the events the user has directed towards it. 

It is not necessary for you to interact with the Notifier directly in your applica- 
tion. SunView has a two-tiered scheme in which the packages that support the 
various objects — panels, canvases, scrollbars, etc. — interact with the Notifier 
directly, registering their own callback procedures. The application, in turn, 
registers its own callback procedures with the object. 

Typically, when writing a SunView application you first create the various win- 
dows and other objects you need for your interface, and register your callback 
procedures with the objects. Then you pass control to the Notifier. The work is 
done in the various callback procedures. 

Let’s illustrate the relationship of the Notifier, the SunView objects and the 
application by taking iconedit as an example. Figure 2-13 illustrates how the 
Notifier receives UNIX input and calls back to iconedit’s subwindows, which 
in turn call back to procedures supplied by iconedit. 
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Figure 2-13 Flow of Input Events in iconedit, a SunView Application 
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The main point of the diagram on the preceding page is to make clear the 
double-tiered callback scheme. How you register the callback procedures will be 
explained in the chapters on panels and canvases. 

One point worth mentioning is the distinction between the “event procedures” for 
the canvases and the “notify procedures” for the panel items. They are all call- 
back procedures, but they have different purposes. The canvas’s event procedure 
doesn’t do much work — basically it calls out to the application’s event pro- 
cedure each time an event is received. The application sees every event and is 
free to interpret the events however it likes. 

The event procedure for panels, on the other hand, does quite a bit of processing. 
It determines which item should receive the event, and places its own interpreta- 
tion on events — the middle mouse button is ignored, left mouse button down 
over an item is interpreted as a “tentative” activation of the item, etc. It does not 
call back to the notify procedure for the item until it receives a left mouse button 
up over the item. So panel item notify procedures are not so much concerned 
with the event which caused them to be called, but with the fact that the button 
was pushed, or a new choice made, etc. 

Calling the Notifier Directly As mentioned previously, for many applications you will not need to call or be 

called by the Notifier directly — the Notifier calls back to the subwindows, 
which in turn call back to your application. 

However, if you need to use signals, or be notified of the death of a child process 
which you have spawned, you do need to call the Notifier directly. 

The Notifier also provides calls which allow you to insert your own routine in the 
event stream ahead of a window. This technique is known as interposition. 

When and how to call the Notifier directly is covered in Chapter 17, The Notifier. 
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This chapter outlines the SunView interface, the SunView libraries, header files, 
object handles, attributes and the standard functions applicable to objects of each 
type. 

SunView Libraries The SunView functions that an application calls are mostly in the library file 

/usr/lib/libsuntool . a if you are using the archive libraries and 
/usr/lib/libsuntool . so if you are using the shared libraries. These 
libraries include the code to create and manipulate high-level objects such as 
frames, panels, scrollbars and icons. These packages in turn call routines in 
/usr/lib/libsunwindow . a or /usr/lib/libsunwindow. so to 
create and manipulate windows and interact with the Notifier. These in turn call 
routines in /usr/lib/libpixrect . a or /usr/lib/libpixrect . so 
that do the drawing on the screen. 

NOTE Shared libraries were introduced in SunOS 4.0. The main benefit to using shared 
libraries is that the executables are much smaller (for example, 24K instead of 
1Mb for textedit alone) because the libraries are loaded dynamically at runtime 
and are subsequently shared by other executables. Additionally, when the shared 
libraries are recompiled, new functionality is added, or bug fixes are made, the 
client applications don’t need to be recompiled and linked unless the . so or an 
interface changed. For more information on shared libraries, see Programming 
Utilities and Libraries. 



Compiling SunView Programs To compile a SunView program you must link in these three libraries, and, 

because they are built one on top of another, their order is important. For exam- 
ple, to compile a typical SunView application whose source is myprog . c, you 
would type in the command: 

% cc -o myprog myprog. c -lsuntool -lsunwindow -lpixrect 

v J 

Header Files The basic definitions needed by a SunView application — covering windows, 

frames, menus, icons and cursors — are obtained by including the header file 
<suntool/sunview . h> . Definitions for the other types of object are found 
in their own include files — <suntool/canvas . h>, <suntool/text . h>, 
<suntool/panel . h>, etc. 
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Object Handles When you create a Sun View object, the creation function returns a handle for the 

object. Later, when you wish to manipulate the object or inquire about its state, 
you pass its handle to the appropriate function. This reliance on object handles is 
a way of information-hiding. The handles are opaque in the sense that you can’t 
“see through” them to the actual data structure which represents the object. 

Each object type has a corresponding type of handle. The window types of 
Frame, Canvas, Textsw, Tty and Panel are grouped under the type Win- 
dow. So, for example, you can declare a panel as either a Panel or a Window, 
whichever is most appropriate. The other object types are Panel item, Menu, 
Scrollbar, Cursor, and Icon. 

Since C doesn’t have an opaque type, all the opaque data types mentioned 
above are typedef ’d to the UNIX type caddr_t (for “character address 
type”), which in turn is ty pede f ’d to char * . 

In addition to the opaque data types, there are several typedef s which refer not 
to pointers but to structures: Event, Pixfont, Pixrect, Pixwin, Rect, 
and Recti i st. Generally pointers to these structures are passed to SunView 
functions, so variables in a user program are declared as Event *, Pixwin 
*, etc. The reason that the is not included in the typedef is that the struc- 
tures are publicly available, in contrast to the object handles, which include the 
and which refer to structures that are not publicly available. 

The SunView data types are summarized in Chapter 19 , SunView Interface Sum- 
mary. 

Problems can arise when a SunView function call to create an object (frame, 
panel, or panel_item for example) returns NULL. You cannot blindly use such a 
pointer without first checking whether it is NULL. Although it is common prac- 
tice not to check pointers, and usually does not create problems, it is careless pro- 
gramming and can lead to trouble. (Sadly, the examples in this manual do not 
always conform to this principle.) 



Attribute-based Functions A model such as that used by SunView, which is based on complex and flexible 

objects, presents the problem of how the client is to manipulate the objects. The 
basic idea behind the SunView interface is to present a small number of func- 
tions, which take as arguments a large set of attributes. 

For a given call to create or modify an object, only a subset of the set of all appli- 
cable attributes will be of interest. So that only the relevant attributes need be 
mentioned, SunView functions make use of variable -length attribute lists. An 
attribute list consists of attribute/value pairs, separated by commas, and ending 
with a zero. 

Each type of object has its own set of attributes. The attributes have prefixes 
which indicate the type of object they apply to, i.e. FRAME *, TEXTSW_*, 
CANVAS__*, TTY__*, PANEL_*, MENU_*, CURSOR_*, ICON_*, SCROLL_*, 
etc. 

In addition to the sets of attributes applying to each type of object, there is a set 
of window attributes of the form WIN_* which apply to all window objects. 
These are attributes such as WIN_HEIGHT and WIN_WIDTH, which apply to all 
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Standard Functions 



Example of SunView-Style 
Programming 



Attribute List Size 



windows regardless of whether they happen to be panels, canvases, etc. 

For objects of all types there is a set of standard Junctions to create and destroy 
the object and to get and set the object’s attributes. 

Window functions are prefixed with window , yielding 

□ window_create ( ) , 

□ window_get ( ) , 

□ window_set ( ) , and 

□ window_destroy ( ) . 

Providing common window functions reduces the complexity of the interface. 
Non- window functions are prefixed with the name of the object. So, to take 
menus as an example, the standard functions are 

□ menu_create ( ) , 

□ menu_get ( ) , 

□ menu_set ( ) , and 

□ menu_destroy ( ) . 



The flavor of the interface is illustrated with the following code fragment, which 
creates a scrollbar with a width of 10 pixels and a black bubble. Later, the 
scrollbar’s width is changed to 20 pixels. Finally, the scrollbar is destroyed: 





Scrollbar bar; 

bar = scrollbar create (SCROLL WIDTH, 


10, 


^ 




SCROLL_BUBBLE_COLOR , 


SCROLL BLACK, 






0); 








scrollbar_set (bar, SCROLL_WIDTH , 20, 
scrollbar_destroy (bar ) ; 


0); 










2 



Note the zero which terminates the attribute lists in the *_create ( ) and 
*_set { ) calls. The most common mistake in using attribute lists is to forget 
the final zero. This will not be flagged by the compiler as an error; however, it 
will cause SunView to generate a run-time error message. 

As you can see from the example above, you can specify several attributes in a 
single *_create ( ) or *_set ( ) call. The maximum length of attribute lists 
in SunView is 250; see Maximum Attribute List Size in Chapter 18, Attribute 
Utilities. 
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Reserved Namespaces SunView reserves names beginning with the object types, as well as certain other 

prefixes, for its own use. 

The prefixes listed below should not be used by applications in lower, upper, or 
mixed case. Also there are symbols not covered by this table that are listed in the 
#include files, for example: TRUE, FALSE, True, False, strdup, 
strequal, ord, FOREVER. 

Check the # include files before naming any global variables in your applica- 
tion. 

Table 3 - 1 Reserved Prefixes 



ACTION_ 


icon_ 


scroll_ 


alert_ 


menu_ 


seln_ 


attr_ 


notify_ 


textsw_ 


canvas_ 


panel_ 


text_ 


cursor_ 


pixrect_ 


toolsw_ 


def aults_ 


pixwin_ 


tool_ 


ei_ 


pr_ 


ttysw_ 


es_ 


pw 


tty_ 


event_ 


rect_ 


window_ 


ev_ 


rl_ 


win_ 


frame_ 

help_ 


scrollbar_ 


wmgr_ 
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Using Windows 



This chapter describes how to build SunView applications out of frames and 
subwindows. 

The first section presents the basic window routines. Succeeding sections give 
examples, ranging from the simplest possible application to a moderately useful 
file manager. For quick reference, the examples are given in the table below: 

Table 4-1 Window Usage Examples 



Example 


Description 


Illustrates 


helioworld 


Minimal SunView program. 


Compilation, frames 


simple _panel 


Panel w/message and button. 


Basic attributes, panels 


lister 


Front end to Is 


Panels, tty subwindows 


filer 


File manager 


Pop-ups, Selection Service 


image browser _1 


Displays images 


Subwindow layout 


image browser 2 


Displays images 


Row/column space 



Summary Listing and Tables To give you a feeling of what you can do with frames and subwindows, the fol- 

lowing page lists the available window and frame attributes, functions and mac- 
ros. Many attributes are discussed as they occur in the examples, and in other 
chapters (use the Index to check). However, this chapter does not attempt com- 
plete coverage of all the attributes. All are briefly described with their arguments 
in the window and frame summary tables in Chapter 19, SunView Interface Sum- 
mary: 

□ the Window Attributes, 

□ the Frame A ttribu tes, 

□ the Window Functions and Macros, 

□ the Command Line Frame Arguments. 
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Window Attributes 




WIN BELOW 


WIN_FI T_WIDTH 


WIN_PERCENT_WIDTH 


WINBOTTOMMARGIN 


WIN_F0NT 


WIN_PICK_INPUT_MASK 


WIN_CLIENT_DATA 


WIN_GRAB_ALL_INPUT 


WIN_PIXWIN 


WIN_COLUMNS 


WIN_HEIGHT 


WIN_RECT 


WIN_COLUMN_GAP 


WI N_H0R I ZONT ALSCROLLBAR 


WINRIGHTMARGIN 


W I N_C0 LUMN_W IDTH 


WIN_IGNORE_KBD_EVENT 


WIN_RIGHT_OF 


WIN_CONSUME_KBD_EVENT 


WI N_IGNORE_KBD_EVENTS 


WIN_ROW_GAP 


WIN_CONSUME_KBD_EVENTS 


WIN_IGNORE_PICK_EVENT 


WIN_ROW_HEIGHT 


WIN_CONSUME_PICK_EVENT 


WIN_IGNORE_PICK_EVENTS 


WINDROWS 


WIN_CONSUME_PICK_EVENTS 


WIN_INPUT_DESIGNEE 


WI N_SCREEN_RECT 


WIN_CURSOR 


WI N_KBD_FOCUS 


WINJ5H0W 


WIN_DEVICE_NAME 


WIN_KBD_INPUT_MASK 


WI N_TOP_MARG I N 


WIN_DEVICE_NUMBER 


WIN_LEFT_MARGIN 


WIN_TYPE 


WIN_ERROR_MSG 


WIN_MENU 


WIN_VERTICAL_SCROLLBAR 


WIN_EVENT_PROC 


WI N_MOUSE_XY 


WIN_WIDTH 


WIN_EVENT_STATE 


WIN_NAME 


WIN_X 


WIN_FD 

WIN_FIT_HEIGHT 


WIN_OWNER 

WIN_PERCENT_HEIGHT 


WIN_Y 



Frame Attributes 



FRAME_ARGS 

FRAME_ARGC_PTR_ARGV 

FRAME_BACKGROUND_COLOR 

FRAME CLOSED 

FRAME_CLOSED_RECT 

FRAME_CMDLINE_HELP_PROC 

FRAME CURRENT RECT 



FRAME_DEFAULT_DONE_PROC 

FRAME_DONE_PROC 

FRAME_EMBOLDEN_LABEL 

FRAME_FOREGROUND_COLOR 

FRAME_ICON 

FRAME_I NHERI T_COLORS 

FRAME LABEL 



FR AME_NO_CONF I RM 

FRAME_NTH_SUBFRAME 

FRAME_NTH_SUBWINDOW 

FRAME_NTH_WINDOW 

FRAME_OPEN_RECT 

FRAME_SHOW_LABEL 

FRAME SUBWINDOWS ADJUSTABLE 



window_bell (win) 

window_create ( owner , type, attributes) 

window_default_event_proc (window, event, arg) 

windowdestroy ( win ) 

window_done ( win ) 

windowf it ( win ) 

window_f it_height ( win ) 

window fit width (win) 



Window Functions and Macros 



window_get (win, attribute) 
:ributes) window_loop( subframe) 

low, event, arg) window__main_loop(base_f rame) 

window__read_e vent (window, event) 
window_refuse_kbd_focus (window) 
window_release_event_lock (window) 
window_return ( value ) 
window set (win, attributes) 
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4.1. Basic Routines 



Creating a Window 



Initiating Event Processing 



Modifying and Retrieving 
Window Attributes 



This section introduces the basic routines for using windows. It explains how to 
create, modify, and destroy windows. 

You create all windows with the function: 

Window 

window_create (owner, type, attributes) 

Window owner ; 

<windowtype> type; 

<attribute-list> attributes; 

If you recall from Chapter 2, The SunView Model , a SunView application is 
implemented as a hierarchy of frames. Each frame owns one or more subwin- 
dows. The frame at the top of the hierarchy (the base frame) will have a null 
owner. In the above function, the owner parameter is the handle of the window 
to which the window returned by window_create ( ) will belong. The type 
parameter is the type of the new window; for example, FRAME, PANEL, 
TEXTSW, CANVAS, or TTY. 

A very simple example of this function would be to create a panel belonging to a 
frame called base_f rame, you would use: 

Panel panel; 

window_create(base_f rame, PANEL, 0); 



The window_create ( ) call does not display the frame on the screen. You 
bring it to life after creating a base frame and its subwindows and subframes, by 
calling window_main_loop (base_f rame ) . This call displays the frame 
on the screen and begins processing the events by passing control to the Notifier. 
Chapter 2, The SunView Model , gave a brief explanation of the Notifier. 

Keep in mind that subframes are treated different from base frames because they 
are not tied to the base frame that is activated in the window_main_loop ( ) 
call. In addition, if you create a subframe with WIN_SH0W set to TRUE, when 
the user tries to manipulate the subframe ‘garbage’ data will appear on the 
screen. 

You modify and retrieve the value of window attributes with the following two 
functions: 

int 

window_set (window, attributes) 

Window window; 

<attribute-lisl> attributes; 

caddr_t 

window_get (window, attribute) 

Window window; 

Window attribute attribute; 
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Destroying Windows 



NOTE If you call window_get ( ) and specify an inappropriate attribute, a zero will 

be returned. For example, a sub frame cannot be closed. Therefore, the call 
window_get ( sub_f rame , FRAME_CLOSED_RECT ) will not work, so the 
value returned will be zero. A segmentation violation will occur if an attempt is 
made to dereference the return value. 

When you get a pointer back from window get ( ) , the pointer points into a 
private data structure, whose contents may change . 7 

You destroy windows with the following two functions: 
int 

window_des troy ( window) 

Window window; 



int 

window_done ( window ) 

Window window; 

The difference between these two is that window_destroy ( ) destroys only 
window and its subwindows and subframes. window_done ( ) , on the other 
hand, destroys the entire hierarchy to which the subwindow or subframe belongs. 

When window_destroy ( ) is called on a window, the corresponding file 
descriptors cannot be used again until the Notifier is called. The file descriptor 
associated with the window is not reclaimed until the notifier has a chance to dis- 
tribute notifications again. 

The way window_destroy ( ) works is that it asks the window owner if it is 
willing to be destroyed. If so, it queues up a notification procedure to destroy the 
window. This delay protects the program from destroying a window that is being 
accessed in the current call stack. You can work around this restriction, assum- 
ing you never reference this window again, by calling 
notify_f lush_pending ( ) after calling window_destroy ( ) . 



7 For most attributes the pointer returned by window_get ( ) points into per-window storage, but for some 
the storage is static, per-process data. These attributes are flagged in the tables Chapter 19, SunView Interface 
Summary. 
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Figure 4-1 Hello World Window' 




This window is “alive” within the SunView user interface; it can be closed, 
moved, resized, hidden, etc. When closed, a default icon is displayed, which 
contains the text from the frame header. 
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4.3. Example 2 — 

simple _panel 



The next program is more complex than the first program. It creates a frame that 
contains a frame label and a panel that contains a panel button and a message. 
This program also includes an image that appears when the window closes down 
to an icon. Some basic attributes dealing with fonts, icons, help, error messages 
and parsing command-line flags are introduced. 



y**************************************************************************y 
/* */ 

/* simple_panel . c */ 

/* V 

/* V 

/* This program displays a frame with the frame label "hello_world_panel " */ 
/* and a panel which contains the panel message "Push button to quit" and */ 
/* a panel button "Good-bye" . The user of this application has the */ 

/* ability to close, move, resize, hide, redisplay, or quit the window. */ 

/* */ 

# include <stdio.h> 

# include <suntool/sunview. h> 

# include <suntool/panel . h> 

# include <suntool/icon . h> 
static void quit_proc(); 

Frame frame; 

Panel panel; 

Pixfont *bold; 

Icon icon; 

static short icon image [] = { 

# include <images/hello_world . icon> 

} ; 

mpr_static(hello_world, 64, 64, 1, icon_image) ; 

main(argc, argv) 

int argc; char **argv; 

{ 

bold = pf_open ( "/usr/lib/f onts/f ixedwidthf onts/screen . b . 12" ) ; 
if (bold == NULL) exit(l); 

icon = icon_create( ICON_IMAGE, &hello_world, 0); 
frame = window_create(NULL, FRAME, 

FRAME_LABEL, " hello_world_panel " , 

FRAME_ICON, icon, 

FRAME_ARGS, argc, argv, 

WIN_ERROR_MSG, "Can't create window.", 

0); 

panel = window_create ( frame , PANEL, WIN_FONT, bold, 0); 
panel_create_item (panel , PANEL_MESSAGE, 

PANEL_LABEL_STRING , "Push button to quit.", 0) ; 
panel_create_item ( panel , PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "Good-bye", 0, 0), 
PANEL_NOTIFY_PROC, quit_proc, 

0 ); 

window__f it ( panel ) ; 
window_f it ( frame) ; 
window_main_loop ( frame) ; 

} 

static void 
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quit_proc ( ) 

t 

window_set (frame, FRAME_NO_CONF I RM , TRUE, 0); 
window_destroy (frame) ; 

} 

k 



This program creates a frame containing a single panel with a message and a but- 
ton: 

Figure 4-2 Hello World Panel 



he 1 1 o wor 1 d_pane 1 



jjPushbuttontoq 



The features and attributes used in the above program are discussed below. 

Some Frame Attributes The attributes are discussed below in the order that they appear in the above 

panel. 

FRAME_LABEL The string given as the value for FRAME LABEL will appear in a black frame 

header strip at the top of the frame. If you do not want the label and the frame 
header to appear, then set the attribute FRAME_SHOW_LABEL to FALSE. 



FRAME ICON 




The program used FRAME_ICON to specify the icon to be shown when the frame 
is closed. This is done by first using the macro mpr static ( ) to define a 
static memory pixrect to contain this data, with hello world as the name of 
the pixrect. The next three arguments specify the width, height, and depth of the 
image. Typically, for an icon, this is 64, 64, and 1. The final argument is an 
array of shorts that contains the bit pattern of the icon image. It takes its image 
from the file /usr/include/images/hello_world . icon. This stati- 
cally defined image is passed to icon_create ( ) at runtime. 

The application uses FRAME_ARGS 8 to pass command-line arguments given by 
the user to the frame. A set of command line arguments are recognized by all 
frames. These arguments allow the user to control such basic attributes as the 
frame’s dimensions and label and whether the frame’s initial state is open or 
closed, etc. These arguments begin with -W; for a complete list of them see the 
Command Line Frame Arguments table in Chapter 19, SunView Interface Sum- 
mary. 



8 As an alternative to FRAME_ARGS, you can use FRAME_ARGC_PTR_ARGV, which takes a pointer to 
argc, rather than argc itself. This attribute causes window create ( ) to strip all arguments beginning 
with -W out of argv, and decrement argc accordingly. 
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WIN_ERROR_MSG 

Panels 

Fonts 

Panel Items 

Notify Procedure 

Window Sizing — 

window_fit( ) 



WIN_ERROR_MSG provides a simple form of error checking. If this attribute is 
not specified, then window_create ( ) will return 0 on failure. If a value for 
WIN_ERROR_MSG is specified and window_create ( ) fails, then it will print 
the error message on stderr and exit with a status of 1. 

The panel is created by calling window create ( ) with the previously created 
frame as the owner and PANEL as the window type. 

By default, text in the panel is rendered in the default system font, which 
window_create ( ) obtains by calling pf_def ault ( ) 9 The program 
specified a font by first opening the font with pf _open ( ) , and then passing it 
into the panel as WIN_F0NT. 

NOTE In the SunView context, setting WIN_FONT is not equivalent to specifying a font 
at run time with the -wt command-line argument: -wt sets the default system 
font, wiN_FONT does not. The only window types that currently make use of 
WIN_F0NT to render characters are panels and text subwindows. 



The panel contains two panel items: the message saying “Push button to quit.” 
and the Goodbye button. They are created with panel_create_item( ) . 

The concept of callback procedures was introduced in Chapter 2, The SunView 
Model. Callback procedures for panel items are known as notify procedures. 

The program registered its notify procedure quit_proc ( ) with the Goodbye 
button using the attribute PANEL NOTIFY PROC. quit_proc ( ) is called 
when the user selects the button. It in turn calls window_destroy ( ) , which, 
as explained in the earlier subsection on Destroying Windows , causes 
window_main_loop ( ) to return. Before calling window_destroy ( ) , it 
disables the standard SunView confirmation by setting the attribute 
FRAME_NO_CONFlRM for the frame. 

The final feature illustrated by the example is the use of the window_f it ( ) 
macro. This macro causes a window to exactly fit its contents. 

The contents of a panel are its panel items; the contents of a frame are its subwin- 
dows. Therfore, the example program calls window f it ( ) twice, first fitting 
the panel around its two items, then fitting the frame around its panel. 

A window_f it_width( ) macro and a window f it_height ( ) macro 
are used to permit adjusting in only one dimension. These correspond to the 
window attributes WIN FIT width and WIN FIT HEIGHT. 



9 For details on fonts see the Pixrect Reference Manual. 
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Fitting Frames Around 
Subwindows 



4.4. Example 3 — lister 



Figure 4-3 



Since Release 3.2, if you use window_f it ( ) or its variants for sizing the 
width and height of a frame, you need to be careful that the subwindows have 
some specified size, or they will be shrunk very small by the window_f it ( ) 
call. Usually you give a subwindow a fixed size in one or both dimensions, or 
size it to be a percentage of the frame’s size. The default size of a frame is that it 
encloses an area 34 rows by 80 columns in its default font. 

Figure 4-3 illustrates a program to help manage files. The first version simply 
lets the user list files in the current directory, forming a front-end to the Is (1) 
command: 



lister 











||me: *.c^ 






[ List J [ Quit ] 


Icon a IX Is *.c II 


briggs.tools.c 


fi ler_save.c 


i leaf .c 


order_test2.c 


canvas_demo.c 


gsh_panel .c 


items.demo.c 


order_test3.c 


conflrm.c 


hel lo_world . c 


lister. c 


order_test4. c j 


dg_cycle.c 


hello_world2.c 


lockscreen.c 


panel . c 


dir tool .c 


helper_save.c 


margin_test .c 


panel_text.c 


fi ler . c 


helper_versionl .c 


misc_merge.c 


sunvieu_manual . c 


filer3_save.c 
coralX [] 


1con_test.c 


order_testl .c 





J 



The tool presents two subwindows. The top subwindow is a control panel with a 
text item. It contains a place to specify the files to be listed, a List button, and a 
Quit button. 

Below the control panel is a tty subwindow. When the user pushes the List but- 
ton, the program constructs a command string consisting of the string “Is ”, fol- 
lowed by the value of the File: item, followed by a newline, and inputs the com- 
mand string to the tty subwindow by calling ttysw input ( ) . 

The program is listed in its entirety below. 

Notice that the frame, the panel and the tty subwindow are all declared as type 
Window. They could just as well have been declared as type Frame, Panel 
and Tty. 
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y’****************************************************************/ 

/* V 

/* lister. c */ 

/* */ 

/★★A*************************************************************/ 

/*★**★******************■*****•************★*********•*★******★*****/ 

/* V 

/* This program helps the user to manage files. The user is */ 
/* able to list the files in the current directory. This */ 

/* application consists of two subwindows. The first subwindow */ 
/* consists of a list and a quit button. This subwindow is the */ 
/* control panel of the application. The second subwindow, */ 

/* the tty subwindow, is directly below the control panel. This*/ 

/* tty subwindow lists the files specified. The user also has */ 

/* the ability to close, move, resize, hide, redisplay, or quit */ 
/* the window. */ 

/* V 

^/****************************************************************/ 



#include <suntool/sunview . h> 

#include <suntool/panel . h> 

#include <suntool/tty . h> 

Window frame, panel, tty; 

Panel_item fname_item; 

static void ls_proc(), quit_proc(); 

main(argc, argv) 

int argc; char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FR AME_L ABEL , "lister", 

0); 

panel = window_create( frame, PANEL, 0); 

create_panel_items ( ) ; 

tty = window_create ( frame , TTY, 0); 

window_main_loop ( frame) ; 

exit ( 0 ) ; 

} 

create_panel_items { ) 

{ 

fname_item = panel_create_item { panel , PANEL_TEXT, 

PANEL_LABEL_STRING, "File: ", 

PANEL_VALUE_DISPLAY__LENGTH , 55, 

0); 

panel_create_item (panel , PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "List", 5, 0), 

PANEL_NOT IFY_PROC , ls_proc, 

0 ); 

panel_create_item (panel , PANEL_BUTTON , 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "Quit", 5, 0), 

PANEL_NOTIFY_PROC , quit_proc, 

0); 

window_fit_height (panel) ; 

} 

static void 

ls_proc (/* ARGS UNUSED */) 

{ 

char cmdstring [ 256 ] ; 

V 2 
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/* sprintf (cmdstring, "Is %s n", panel_get_value ( f name_item) ) ; */ 
/* vmh - 1/90 */ 

sprintf (cmdstring, "Is %s 0, panel__get_value( fname_item) ) ; 
ttysw_input ( tty , cmdstring, strlen ( cmdstring) ) ; 

} 

static void 

quitproc (/* ARGS UNUSED */) 

{ 

window_des troy ( frame) ; 

} 



4.5. Example 4 — filer Our next example builds on the simple front end to Is given in the previous 

example to create a more interesting file manipulation tool. This application 
illustrates the use of the text subwindow, the Selection Service, and pop-ups — 
windows that appear on the screen and disappear dynamically during execution 
of a program. 

In appearan cz, filer is similar to lister, in that it contains a control panel and tty 
subwindow. The user specifies the directory and file, and pushes the List Direc- 
tory button, causing the Is command to be sent to the tty subwindow: 

Figure 4-4 filer 



[List Directory] [Set Is flags] [Edit] [Delete] [Quit] 
Filing Mode: C Use "File:" item 



Di rectory : /usr/vi ew/doc/app/code 

File: *.c 

♦ 

/usr/vi ew /doc /app /code /confi rm . c 
/usr/view/doc/app/code/dctool .c 
/usr/vi ew/doc/app /code /f i ler .c 
/usr /view /doc /app/code/font_menu .c 
/usr/vi ew/doc/app/code/hel lo_world .c 
/usr/vi ew/doc/app/code/ image_browser_l ,c 
/usr/vi ew/doc/app/code/image_browser_2 ,c 
/usr/view/doc/app/code/1 ister ,c 
/usr/vi ew/doc/app/code/menugenproc .c 
/usr/vi ew/doc/app/code/resl ze_demo .c 
/usr/vi ew/doc/app/code/sel n_demo .c 
/usr/vi ew/doc/app/code/showcol or ,c 
/usr/vi ew/doc/app/code/simple_canvas ,c 
/usr/view/doc/app/code/simple_panel .c 
/usr/vi ew /doc /app/code/sphe res ,c 
/usr/vieu/doc/app/code/tty_io ,c 
/usr/view/doc/app/code/typein ,c 
polar% [] 



There are three new buttons, each of which illustrates a typical use of pop-ups: 
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Set Is flags a pop-up property sheet for setting options to Is; 

Edit a pop-up text subwindow for browsing and editing files; 

Delete a pop-up confirmer which forces the user to confirm or cancel. 

The three buttons are discussed in the pages that follow. The discussion makes 
reference to specific routines in the filer program, which is listed in its entirety as 
filer in Appendix A, Example Programs. 

Pop-ups In Sun View, pop-ups are implemented as subframes containing subwindows. 

The subframe, along with its subwindows, is displayed and undisplayed as 
needed. Pop-ups may be displayed in either a blocking or a non-blocking mode. 
Examples of SunView pop-ups include the mailtool’s composition window 
and textedit’s search and replace. 

Pop-up Text Subwindow The Edit button illustrates a non-blocking pop-up. When the user selects a 

filename and presses the button, a pop-up text subwindow containing the file 
appears: 

Figure 4-5 A Pop-up Text Subwindow 



filer 



[List Directory) [Set Is flags] [Edit] [Delete] [Quit] 
Filing Mode: C Use "File:" item 



Directory: /usr/vieui/doc/app/code 

File: confirm.c 

± 



/usr/view/doc/app/code/conf i rm , c 
/usr/view/doc/app/code/dctool ,c 



/usr 




/usr 




^* ************ ******************************************** 


/usr 




*/ 


/usr 




#ifndef lint 


/usr 




static char sccsid[] ■ "@(#)conf i rm .c 1.4 87/01/07 Copyr 1 


/usr 




986 Sun Micro " ; 


/usr 




#en dif 


/usr 




^r********************************************************* 


/usr 




/ 


/usr 






/usr 




#inc1ude <suntool /sunvieu .h> 


/usr 

/i j«;r 




linclude <suntool /panel . h> 


/usr 




static Frame init confirmer(); 


/usr 




static int confirm(); 


pol a 




static void yes_no_ok(); 






int 






conf i rm_yes(message) 




"W 

Ti 





Both the subframe and text subwindow for the pop-up are created at initialization 
time with the calls: 
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Pop-up Property Sheet 





edit_frame = window_create(base_frame, FRAME, 

FRAME_SHOW_LABEL, TRUE, 

0 ) ; 

editsw = window_create(edit_frame, TEXTSW, 0); 
s > 



When the user selects the Edit button, the notify procedure edit proc ( ) is 
invoked. This function first calls the Selection Service to get the name of the file 
the user has selected. 

It then loads the file into the text subwindow, sets the frame header to the 

filename, and displays the frame with these two calls: 
— 

window_set ( editsw, TEXTSW_FILE, filename, 0); 

window_set (edit_frame, FRAME_LABEL, filename, WIN_SHOW, TRUE, 0) ; 
v 



The property sheet shown in Figure 4-6 is a typical example of a non-blocking 
pop-up. By pushing the Set Is flags button, the user can get a property sheet 
which allows him to set some of the options to the Is command. While the pro- 
perty sheet is displayed, the user can continue to interact with the application, 
setting options now and then. The user can cause the pop-up to disappear at any 
time by pushing the Done button, selecting Done from the subframe’s menu, or 
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by pressing the Sun View function key labelled 1 Open 1 . 
Figure 4-6 A Non-blocking Pop-up 



(List Directory) [Set Is flags) (Edit 1 ) [Delete] [Quit] 



Filing Mode: C Use "File:" item 



D1 rectory : /usr/vi eu/doc/app/code 

File: confirm.c 



/usr/vieu/doc/app/code/conf i rm .c 
/usr/vieu/doc/app/code/dctool ,c 
/usr/vi ew/doc/app/code/fi ler .c 
/usr/vlew/ii 



/usr/view/< 
/usr/view/< 
/usr/vi eui/< 
/usr/vieui/( 



Options for Is command 



Format : 

Sort Order : 



/usr/view/i 
/usr/view/i 
/usr/view/i 
/usr/view/< 

/usr/vieu/< Sort criterion: 

/usr/view/i For directories, list: 

Recursively list subdirectories? 
Indicate type of file? 

[Done] 

/us r / v i ew / s ? -- 1 - 

/ u s r / v i eu / doc/aa3p7^ie7?t\ 



C Descending 



C Contents 



C No 



app/coae/tty_to ,c 
/usr/vieu/doc/app/code/typein .c 
polar% [] 



Invoking the ‘Props’ Menu Item Two attributes are used to control whether the ‘Props' menu item is active or able 

to be invoked in the frame’s menu. The code fragment given below is taken 
from the filer program. 

The FRAME_PROPS_ACTlON_PROC attribute specifies which procedure will 
be called when the ‘Props’ menu item is chosen or the ( Props 1 key is pressed. In 
the code below, FRAME_PROPS_ACTlON_PROC specifies that the procedure 
ls_f lags_proc ( ) is called when the [ Props ] key is pressed. 

The FRAME_PR0PS_ACTIVE attribute specifies whether the procedure that is 
specified by the FRAME_PR0PS_ACTI0N_PR0C will be called or not. If the 
attribute FRAME_PROPS_ACTIVE is TRUE, then the frame menu will contain 
an un-greyed ‘Props’ menu item. If the attribute FRAME_PROPS_ACTl VE is 
FALSE, then the frame menu will contain a greyed out ‘Props’ menu item. 





base_frame = window_create ( NULL , FRAME, 


N 




FRAME_ARGS , 


argc, argv, 




F RAM E_L ABEL , 


"filer" , 




FRAME_PROPS_ACTION_PROC , 


ls_f lags_proc , 




FRAME PROPS ACTIVE, 
0); 


TRUE, 






/ 



#sun 

microsystems 



Revision A, of March 27, 1990 





40 SunView Programmer’s Guide 



WIN SHOW 



Pop-up Confirmer 



The display of a non-blocking pop-up is controlled using the WIN_SHOW attri- 
bute. The initialization routine create ls f lags_popup ( ) creates the 
subframe, panel, and panel items for the property sheet. When the subframe is 
created, WIN_SH0W is FALSE. 10 The notify procedure for the Set Is flags but- 
ton, ls_f lags_proc ( ) , simply sets WIN_SH0W to TRUE for the subframe. 1 1 

When the notify procedure for the List Directory button, ls_proc ( ) , is called, 
it calls compose ls options ( ) to construct the appropriate string of flags 
based on the settings of the items in the property sheet. 

Both the property sheet and the editing subwindow described in the preceding 
section are examples of non-blocking pop-ups, in which the application contin- 
ues to receive input while the pop-up is displayed. 

Blocking pop-ups differ in that, when displayed, they receive all input directed to 
the screen. Blocking pop-ups are appropriate when you want to force the user to 
confirm or cancel an irreversible operation before changing the application’s 
state in any way. 

Most uses of blocking pop-ups should use the alert package described in Chapter 
10, Alerts. In the example given below, filer uses an alert for the Delete button 
confirmation. However, if you want to use other panel features, or other kinds of 
windows, then you can use window_loop ( ) for the same effect. 

For example, in Figure @NumberOf(alert-win), when the user makes a selection 
and pushes the Quit button, filer displays a pop-up asking for confirmation. All 
input is directed into this confirmer, and the user is forced to either accept the 
deletion by selecting Yes or cancel it by selecting No : 



10 Note that while WINjSHOW defaults to TRUE for base frames, it defaults to FALSE for subframes. The 
same holds for FRAME_SHOW_LABEL. 

1 1 Note that the subframe won’t actually be displayed until control is returned to the Notifier. 
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Figure 4-7 Pop-up Confirmer 





;i; [List Directory] [Set Is flags] [Edit] [Delete] 




I 


ijj Filing Mode: v Use "File:" item 




I 


| Directory: /usr/view/1.7S/usr/src/usr .bin/sunwindows/suntoo 1/examples 

1 File: | 


ipi apia% Is 
| Makefile 
iji; Makef ile . customer 
$ Makefile.doc 
iji Makef ile. old 

1 sccse 


detool* 

dctool.c 

err 

filer* 

f l 1 at* r* 


menugenproc .c 
resize.demo* 
resize.demo.c 
seln.demo* 




| addnewtest* k 
ijj addnewtest 
| animatecolor*^M 
| animatecolor .c 
bounce* 

| bounce. c 
j;j: canvas_input* 


taL Are you sure you want 


to Quit? 




fTconfirml 


[Cancel] 








iji; canvas .repaint* 

| canvas .repaint.c 
ijj coloredit* 

$ co loredit.c 
jiji confirm. c 
| apia% Q 




image _browser_2* 
image.br owser_2 . c 
loopback* 
loopback. c 
menugenproc* 


tty.io.c 

typein* 

typein.c 






window_loop ( ) The display of a non-blocking pop-up is controlled using the WIN_SH0W attri- 

bute. The display of a blocking pop-up, on the other hand, is controlled with the 
two functions window_loop ( ) and window_return ( ) . 

caddr_t 

window_loop ( subframe ) 

Frame subframe; 



void 

window_return ( returnvalue ) 
caddr_t returnvalue; 

window loop ( ) causes the pop-up to be displayed and receive all input 
directed to the screen. The call will not return until window return ( ) is 
called from one of the pop-up’s notify procedures. The value passed to 
window_return ( ) as return_value will be returned by 
window loop ( ) . Its interpretation is up to the application. That is, it may be 
used to indicate whether the command was confirmed, whether a valid file name 
was entered, and so on. 
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Restrictions on Pop-Up Frames There are some restrictions on pop-up frames displayed using 

window_loop ( ) : 

□ You can only have one subwindow in the pop-up frame. 

□ The only subwindow types that work properly are canvases and panels. 

□ Do not use scrollbars. 

□ Do not set FRAME_CLOSEDtO TRUE. 

□ Do not set WI N_SHOWto TRUE. 

These limitations do not apply to non-blocking pop-ups displayed using 
WIN_SHOW. 

Controlling a Pop-up or Sun’s convention is that only transient items such as pop-ups have shadows. 

Frame’s Shadowing However, using the attribute FRAME SHOW SHADOW you may control the sha- 

dowing effect of a frame or a subframe: 

□ If you want your base frame to have a shadow, then set the attribute 
FRAME_SHOW_SHADOW to TRUE. 

Note that the use of shadow frames □ You may stop a shadow from appearing with a subframe during create time 
consumes an additional file descrip- by FRAME_SHOW_SHADOW to FALSE. 
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4.6. Example 5 — Figure 4-8 illustrates how to specify the size and position of subwindows in order 

image browser _1 to get the layout that you want. This application lets the user view the images in 

files generated by iconedit. The user first presses the List button to get a list- 
ing. The user then selects a file that contains an image and press the Show but- 
ton to view the image: 

Figure 4-8 image browser _1 



image_brouser 



flame. icon 
hel lo_uor Id . i con 
helper .icon 
home. icon 
stop . i con 

sunvi eu.manual . i con 
fcjorld. i con 
coral% Is -1 *.icon 



bi 1 1 . i con 



book. icon ^ 
bulb. icon 
cloun. i con 
f lame. i con 
hel lo_uor Id . i con 
helper. icon 
home . i con 
stop. icon 

sunvi eujmanual . i con 

luorld.icon 

coral% | 



Dir: 

File: *.ii 
{List) (Show) [Quit] 




This example presents a somewhat more complex subwindow layout: the tty 
subwindow has been moved to the left, the control panel to the upper right, and a 
panel for displaying the image added on the lower right. 

Specifying Subwindow Size You can specify the size of a subwindow either in pixels, with WIN_HEIGHT 

and WIN_WIDTH or in terms of rows and columns, with WIN_R0WS and 
WIN COLUMNS. 12 If its dimensions are not specified, then a subwindow will 
extend in the y direction to the bottom edge, and in the x direction to the right 
edge of the frame. In this case the subwindow’s height and width will have the 
special value WIN EXTEND TO EDGE, 13 and will track the edge of the frame 
at run time, expanding or shrinking appropriately when the user resizes the 
frame. 

Keep in mind that if you alter the size of a frame so that it exactly borders on a 
sub window by calling window _f it ( ) , the dimension of the subwindow that 
touches the frame will automatically become WlN_EXTEND_TO_EDGE. 



12 Row/column space is discussed in the next example. 

13 It is meaningless to set the width or height of a frame to WIN EXTEND TO EDGE, and it will interfere 
with subwindow behavior. 
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Default Subwindow Layout The default subwindow layout algorithm is simple. The first subwindow is 

placed at the upper left comer of the frame (leaving space for the frame's header 
and a border). If the width of the previously-created subwindow is fixed, not 
extend-to-edge, then the next subwindow is placed to the right of it. If the width 
of the previously-created subwindow is extend-to-edge, then the next subwindow 
is placed below it, at the left of the frame. 

Explicit Subwindow Layout This default layout algorithm handles only very simple topologies. SunView 

provides attributes that allow you to specify more complex layouts by explicitly 
positioning subwindows. You can position one subwindow relative to another by 
using WiN_BELOW and WIN_RIGHT_0F. These attributes take as their value 
the handle of the subwindow you want the new sub window to be below or to the 
right of. 

image browser _1 , pictured on the preceding page, illustrates the use of 
windowf it ( ) along with explicit subwindow positioning to obtain a particu- 
lar layout. The relevant calls are shown below: 


tty = window_create( frame, TTY, 

WIN_ROWS, 20, 

WIN_COLUMNS, 30, 

0 ); 

control_panel = window_create (frame, PANEL, 0); 

(create panel items...) 

windowf it (control_panel ) ; 

display_panel = window create ( frame, PANEL, 

WIN_BELOW, control_panel , 
WIN_RIGHT_OF, tty, 

0 ); 

wi ndow f i t ( f r ante ) ; 

V 



First the tty subwindow is created with a fixed height and width. Then the con- 
trol panel is created, with no specification of origin or dimensions. 

Since the width of the previous subwindow was fixed, the control panel is placed 
by default just to the right. After its items are created, the control panel is shrunk 
around its items in both dimensions with window_f it ( ) . 

Next, the display panel is created and explicitly positioned below the control 
panel and to the right of the tty subwindow. Both dimensions of the display 
panel default to WlN_EXTEND_TO_EDGE. 

Finally, window f it( ) is called to shrink the frame to the height of the tty 
window and the combined width of the tty window and the control panel. 14 



14 windowf it ( ) causes the window to shrink until it encounters the first fixed border. Subwindows 
which are extend-to-edge don’t stop the shrinking. 
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NOTE One thing to watch out for is that WIN_BEL0W only affects the subwindow’s y 
dimension , and win_RIGHT_OF only affects the x dimension. 

You can also specify the origin of a subwindow in pixels using WIN X and 
WIN Y. The computations for these attributes take the borders and header of the 
frame into account, so that specifying WIN X and WIN Y of 0 will then result in 
the subwindow being placed correctly at the upper left comer of the frame. 

The program resize demo, listed in Appendix A, uses these attributes to lay out 
its subwindows in a non-standard manner. 

If you programmatically change the size or position of subwindows after you 
create them, then you must explicitly re-specify the origin of any subwindows 
that are below or to the right of the altered subwindows. This must be done even 
if you specified the positions of these other subwindows using relative position 
attributes, such as win_below. 

This step is necessary because subwindows are not automatically laid out again 
when the positions and sizes of other subwindows are changed. They are only 
laid out again if the frame changes size. When re-specifying the layout of the 
other subwindows, you can use relative position attributes such as WIN_BEL0W. 

The Rect Structure The attributes WIN_X, WIN_Y, WIN_WIDTH and WIN_height, taken together, 

define the rectangle occupied by a window. This rectangle is actually stored as a 
Rect struct, which you can get or set using the attribute WIN_RECT. The 
definition of a Rect, found in <sunwindow/rect . h>, is: 15 

typedef struct rect { 
short r_left; 
short r_top; 
short r_width; 
short r_height; 

} Rect; 

The Rect is the basic data structure used in SunView window geometry. Where 
complex shapes are required, they are built up out of groups of rectangles. 16 



Changing Subwindow Layout 
Dynamically 



Specifying Subwindow Sizes 
and Positions 



15 The result that a window returns is relative to a frame’s positioning space. It is not self-relative and it is 
not parent-relative. Therefore, WIN RECT should only be used for window positioning operations. Do not use 
it for pw_lock ( ). 

16 For a detailed discussion of rectangle geometry, including useful macros for operating on rectangles, see 
the chapter entitled Reels and Rectlists in the SunView System Programmer' s Guide. 
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4.7. Example 6 — In the next example, when the user specifies a filename and pushes Browse the 

image browser _2 images in the files are displayed in a scrollable panel: 

Figure 4-9 image browser _2 




The point of this example is to illustrate how you can use row! column space to 
specify the size of a subwindow. The goal was to make the panel just the right 
size to display a single page of icons, with four rows, four columns, and 10 pixels 
of white space around each icon. 

Row/Column Space Row/column space refers to a logical grid defining the rows and columns of a 

window. You can define the row/column space for a window by using the attri- 
butes in the following table: 

Table 4-2 Window Row/Column Geometry Attributes 



Attribute 


Description 


Default 


Def. in Panels 


W I NBOT T OMMARG I N 


Bottom margin. 


0 


(same) 


WIN _COLUMN_GAP 


Space after columns. 


0 


(same) 


WIN_COLUMN_WIDTH 


Width of a column. 


Width ofWIN FONT. 


(same) 


WIN_LEFT_MARGIN 


Left margin. 


5 


4 


WIN_RIGHT_MARGIN 


Right margin. 


5 


0 


WIN_ROW_GAP 


Space after rows. 


0 


5 


WIN_ROW_HEIGHT 


Height of a row. 


Height of WIN FONT 


(same) 


WIN_TOP_MARGIN 


Top margin. 


5 18 


4 



18 In frames with headers, the default for WIN TOP MARGIN depends on the system font. With the default 
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Defining a Panel’s Row/Column 
Space 



Positioning Panel Items in 
Row/Column Space 



Using the row/column space attributes, the icon browsing panel pictured on the 
preceding page is specified as follows: 



( 






\ 




Scrollbar scrollbar = scrollbar_create(SCROLL_MARGIN,10 / 0) ; 






bar width = ( int )scrollbar get ( scrollbar , SCROLL_THICKNESS , 


0); 




displaypanel = window_create(base_ 


frame, PANEL, 






WIN_VERTICAL_SCROLLBAR, scrollbar, 






WIN ROW_HEIGHT, 


64, 






WIN COLUMN_WIDTH , 


64, 






WIN ROW_GAP , 


10, 






WIN_COLUMN_GAP , 


10, 






WIN LEFT_MARGIN, 


bar_width + 10, 






WIN TOP_MARGIN, 


10, 






WIN ROWS, 


4, 






WIN COLUMNS, 


4, 






0) ; 








window_set (display_panel , WIN_LEFT_ 


MARGIN, 10, 0); 




l 









This achieves our goal of a panel the right size for a 4x4 array of 64 pixel square 
icons, with 10 pixels of white space around each icon. 



Once you have defined your row/column space, you can position panel items 
within that space with the ATTR_ROW ( ) and ATTR_COL ( ) macros. 19 The code 
fragment shown below shows how the items for the browsing panel are created 
and positioned at the proper row and column each time the Browse button is 
pushed: 



r 






A 


for 


( row 


= 0, image count = 0; image count 


< files_count; row++) 




for 


(col = 0; col < 4 && image count < 


files count; col++) { 




if 


(image = get image (image count)) 


{ 






panel create item(display panel. 


P ANEL_MESSAGE , 






PANEL_ITEM__Y , 


ATTR_ROW ( row) , 






PANEL_ITEM_X , 


ATTR_COL ( col ) , 






PANEL_LABEL_IMAGE , image, 0); 




1 


image_count++ ; 




, 


1 







This example is complicated somewhat by an inconsistency in the way margins 
are handled in the current release of SunView. The left and top margins are used 
in two ways: for determining the size of the panel, and for determining the loca- 
tion of panel items positioned with ATTR COL ( ) and attr row ( ) . The size 
computation does not take into account any scrollbar which may be present; the 
positioning computation, on the other hand, does take the scrollbar into account. 
That is why, in the call to window create ( ) above, WIN_LEFT_MARGIN is 
set to the width of the scrollbar plus 10 pixels, and then set immediately after- 
ward to 10 pixels. 

system font, it defaults to 17. 

19 These “character unit macros” are described fully in Chapter 18, Attribute Utilities. 
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4.8. Attribute Ordering The general rule is that attributes in SunView are evaluated in the order they are 

given. The following two examples of text subwindow calls illustrate how giv- 
ing the same attributes in different orders can produce different effects: 

window_set (textsw, TEXTSW_FILE, "file_l", 0); 

window_set( textsw, TEXTSWJFIRST, 20, TEXTSWFILE, "file_2", 0); 
window_set ( textsw, TEXTSW_FILE, "file_l", 0); 

window_set( textsw, TEXTSW_FILE, "file_2", TEXTSW_FIRST , 20, 0); 

In the first pair of calls, the index is first set to the 20th character of f ile_l, 
then f ile_2 is loaded, starting at character zero. The second pair of calls first 
loads f ile_2, then sets the index in f ile_2 to 20. 

Command-line Arguments The attribute FRAME_ARGS bears special mention. As described in the second 

example in this chapter, simple _panel, this attribute causes the frame to process 
the command-line arguments given by the user at run time. Some of these argu- 
ments correspond to attributes that can be set programmatically; for example, - 
Wh corresponds to WIN_ROWS. 20 

The basic rule, that attributes are evaluated in the order given, applies equally to 
attributes that are explicitly specified in the program and to those that are 
specified at run time using their command-line equivalents. If a given attribute is 
specified more than once, then the last setting is the one that takes effect. You 
can therefore control whether your application or the user has the last word by 
specifying attributes after or before FRAME_ARGS. 

Let’s take a couple of examples: 

window_create ( 0 , FRAME , 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "LABEL FROM PROGRAM", 

WIN_ROWS, 10, 

0); 

window_create ( 0 , FRAME , 

FRAME_LAB EL , "LABEL FROM PROGRAM", 

WIN_ROWS, 10, 

FRAME_ARGS, argc, argv, 

0 ); 

Assume that the program was invoked with a command line containing the fol- 
lowing arguments: 

-W1 "LABEL FROM COMMAND - LINE " -Wh 4 

In the first call, by putting FRAME_ARGS at the start of the list, the application 
overrides the command-line arguments, and guarantees that the frame header will 
read “LABEL FROM PROGRAM” and the height will be 10 lines. 



20 For a complete list of these arguments see the Command Line Frame Arguments table in Chapter 19, 
SunView Interface Summary. 
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In the second call, since FRAME_ARGS appears at the end of the list, the 
command-line arguments override what the application has specified, resulting in 
a label of “LABEL FROM COMMAND-LINE” and a height of 4 lines. 

Keep in mind that if you specify WIN_F0NT, it does not override the font that 
the user specified using -Wt. 

Different Classes of Attributes In the case of different objects, the window attributes (those beginning with 

WIN_) are processed after the others (frame_*, panel_*, and so on). 

Suppose that you want to create a canvas with a scrollbar. You also want the 
logical canvas to expand when the user makes the window bigger, but never to 
shrink past its initial size, even if the user shrinks the window. The initial size of 
the canvas should be the size of the “inner” portion of the window — not includ- 
ing the scrollbar. 



The straightforward approach would be to simply set all relevant attributes when 
the window is created, as in: 










canvas 


= window create ( frame , CANVAS, 






WIN VERTICAL SCROLLBAR, 


scrollbar create(O), 




CANVAS AUTO SHRINK, 


FALSE, 




0); 




k 




/ 



This call, however, results in a canvas which is too big, extending underneath the 
vertical scrollbar. This is because of the order in which the CANVAS_ and WIN_ 
attributes are evaluated. 

Since the window attributes are evaluated after the canvas attributes, the canvas 
size is set according to the initial size of the window, which does not have a 
scrollbar. By the time WIN_VERTICAL_SCR0LLBAR is evaluated, the canvas 
refuses to shrink to the smaller inner portion of the window, since 
CANVAS_AUTO_SHRlNK has already been evaluated and set to FALSE. 

In general, you can force a particular order of evaluation by using separate 
window_set( ) calls, as in: 



canvas = window_create ( frame , CANVAS, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create ( 0 ) , 
0 ); 

window_set( canvas, CANVAS_AUTO_SHRINK, FALSE, 0); 

V ) 



The Panel Package 



The panel package deviates from the norm in that its attributes are generally not 
order-dependent. For example, you can specify the label of an item before the 
font, and the font will be used even though it appears after the label. 

The only thing to watch out for is that you can't change the font in a single call, 
as in: 
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panel_set ( text._it.ein, 








PANEL_FONT, 


f ont_l , 






PAN E L_LAB E L_S TR I NG , 


"Label: ", 






PANEL_FONT , 


f ont_2 , 






PANEL_VALUE , 


" initial value" , 






0); 












/ 



The above call will cause both the label and the value for text_item to be ren- 
dered in font_2. 

4.9. File Descriptor Usage In SunView, each window is actually a device, /dev/win nnn, that is accessed 

through a file descriptor. Other packages such as the selection service also use 
file descriptors. In SunOS there is a limit to the number of file descriptors one 
program can have open. In Release 4.0 the limit was 64, while in 4. 1 it is 256 fds. 
Thus it is possible for your application to run out of file descriptors. 

The following table summarizes how file descriptors are used in SunView. 

Table 4-3 SunView File Descriptor Usage 



Window Type/ 
Package 


FD Usage 


How FDs are used 


FRAME 


1 


1 for unshadowed frames. 


FRAME 


2 


subframes with shadow. 
1 for the subframe. 

1 for the shadow. 


CANVAS 


1 


1 for the window. 


TEXTSW 


3 


1 for the window, 

+ 1 for the file to be edited (if any), 

+ 1 for scratch (the /tmp/Text... file), 




(2) 


2 temporarily created during a save. 


PANEL 


1 


1 for the window. 


TTYSW 


2 


1 for the window, 

+ 1 for the pty (pseudo-tty). 


MENU 


0 


Fullscreen access uses the window’s FD. 


ALERT 


1 


1 for positioning 
Alerts have a frame and a panel; 
however, the FDs are allocated for the 
first alert and reused by subsequent alerts. 


Pointer 


0 


Most pointers are managed by the kernel. 



# sun 

Nr microsystems 
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Table 4-3 SunView File Descriptor Usage — Continued 



Window Type/ 
Package 


FD Usage 


How FDs are used 


Icon 


0 


Frame uses same FD whether open or iconic. 


Scrollbar 


0 


(implemented as a region — read the 
SunView System Programmer’s Guide) 


window manager 


(1) 


1 temporarily used for window 
management operations. 


UNIX 


3 


stdin/stdout/stderr 


framebuffer 


1 


frame buffer FD gets allocated 
automatically with the base frame. The screen 
device must be opened for your program 
to draw on it. 


Selection Service 


3 


selection service fd’s 

are allocated whenever there is something 
that will set or get from the selection 
service. For example, if you put in 
selection service code or the first time 
a panel item is allocated. 




(1) 


This uses sockets to communicate: 

1 for the connection to the service 
+ 1 to receive UDP requests 
+ 1 TCP rendezvous socket for transfers. 
1 transiently opened when a transfer 
is in progress to carry it. 



Counting File Descriptors It is often useful to know how many file descriptors are open. This can be 

accomplished with the f stat ( 2 ) system call. The method is to loop over 
each possible f d, explicitly checking its status with f sta t ( 2 ) . 

The question of the upper limit of the loop can be answered either by choosing a 
suitable number such as 256, or more dynamically by using the getdta - 
blesize ( 2 ) system call to determine the limit. 

An example appears in the Kernel Interface chapter of the System Services Over- 
view. 

File Descriptor Leakage window_return does not destroy the windows in addition to exiting from 

window_loop. 

Some programmers may not realize that window_return exits from 
window_loop, but does not destroy any windows. As a result the file descrip- 
tors associated with the windows remain in use and unavailable for other 
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windows. To reclaim those file descriptors, be sure to call window_destroy. 
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Canvases 



The most basic type of subwindow provided by SunView is the Canvas. A can- 
vas is essentially a window into which you can draw. 

For a demonstration of the various canvas attributes, run the program 
/usr/demo/canvas_demo. For examples of canvases that illustrate event 
handling, run the image editor iconedit(l). iconedit uses two canvases, 
the large drawing canvas on the left, and the small proof area on the lower right. 

In order to use canvases you must include the header file 
<suntool/canvas . h>. 

Summary Listing and Tables To give you a feeling for what you can do with canvases, the following page lists 

the available canvas attributes, functions and macros. Many of these are dis- 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the canvas summary tables in Chapter 
19, SunView Interface Summary : 

□ the Canvas Attributes , 

□ the Canvas Functions and Macros. 
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CANVAS_AUTO_CLEAR 
CANVAS_AUTO_EXPAND 
CANVAS_AUTO_SHRINK 
CANVAS FAST MONO 



Canvas Attributes 

CANVAS_FIXED_ IMAGE 
CANVAS_HEIGHT 
CANVAS_MARGIN 
CANVAS PIXWIN 



CANVAS_REPAINT_PROC 
CANVAS_RESIZE_PROC 
CANVAS_RETAINED 
CANVAS WIDTH 



Canvas Functions and Macros 

canvas_event ( canvas, event) canvas_window_e vent (canvas, event) 

canvas_pixwin ( canvas ) 
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5.1. Creating and Drawing Like all windows in SunView, canvas subwindows are created with 

into a Canvas window_create ( ) . When drawing into a canvas use the canvas pixwin, 

which you can get with the canvas_pixwin ( ) macro. 

The pixwin is the structure through which you render images in a window. You 
draw points, lines and text on a pixwin with a set of functions of the form 
pw_* ( ) — pw__write ( ) , pw_vector ( ) , pw_text ( ) etc. 21 



Example 1: 



Asa beginning example, the following program puts up a canvas containing a 
box with the words “Hello World!”: 



/* */ 

/* simple_canvas . c */ 

/* */ 

/* */ 

/* This program displays a canvas with a box containing */ 
/* the statement "Hello World!". The user of this */ 

/* application has the ability to close, move, resize, */ 

/* hide, redisplay, or quit the window. */ 

/* */ 



ttinclude <suntool/sunview . h> 

#include <suntool/canvas . h> 
main(argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 

Canvas canvas; 

Pixwin *pw; 

/* create frame and canvas */ 

frame = window_create ( NULL, FRAME, 0); 

canvas = window_create ( frame, CANVAS, 0); 

/* get the canvas pixwin to draw into */ 
pw = canvas_pixwin (canvas ) ; 

/* draw top, bottom, left, right borders of box */ 



pw vector (pw, 100, 


100, 


200, 


100, 


PIX 


SRC, 


1); 


pw vector (pw, 100, 


200, 


200, 


200, 


PIX 


SRC, 


l); 


pw vector (pw, 100, 


100, 


100, 


200, 


PIX_ 


SRC, 


i); 


pw vector (pw, 200, 


100 , 


200, 


200, 


PIX 


SRC, 


i); 



/* write text at (125,150) in default font */ 
pw_text(pw, 125, 150, PIX SRC, 0, "Hello World!"); 
window_main_loop( frame) ; 
exit ( 0 ) ; 

1 



The PIX_SRC argument to pw_vector ( ) and pw_text ( ) is a rasterop 
function specifying the operation which is to produce the destination pixel 



21 Pixwins and their associated functions are covered in detail in Chapter 7, Imaging Facilities: Pixwins. 
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values. There are several other rasterop functions besides PIX_SRC; they are 
described in Chapter 2 of the Pixrect Reference Manual. 
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5.2. Scrolling Canvases Many applications need to view and manipulate a large object through a smaller 

viewing window. To facilitate this SunView provides scrollbars, which can be 
attached to subwindows of type canvas, text or panel. 

Example 2: The code below creates a canvas that is scrollable in both directions: 



— 




A 


frame = window create(NULL, FRAME, 0) 






canvas = window create( frame, CANVAS, 






CANVAS AUTO SHRINK, 


FALSE, 




CANVAS WIDTH, 


1000, 




CANVAS_HEIGHT , 


1000, 




WIN_VERTICAL SCROLLBAR, 


scrollbar_create( 0 ) , 




WIN HORIZONTAL SCROLLBAR, 


scrollbar_create( 0 ) , 




0); 






< 




✓ 



The distinction between the dimensions of the canvas and of the window is 
important. In the above example, we set the canvas width and height to 1000 
pixels. Since the dimensions of the canvas subwindow (i.e. WIN_WIDTH and 
WIN_HEIGHT) were not explicitly set, the subwindow extends to fill the frame. 
The frame’s dimensions, in turn, were not explicitly set, so it defaults to 25 lines 
by 80 characters in the default font. The result is a logical canvas roughly the 
area of the screen, which is viewed through a window about one fourth that size. 

NOTE It is necessary to explicitly disable the “ auto-shrink ” feature in the above exam- 
ple. If this were not done, the canvas size would be truncated to the size of the 
window. See Section 5.6, Automatic Sizing of the Canvas. 
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5.3. Canvas Model The components of a canvas subwindow and their relationships can be seen in 

Figure 5-1. 

Figure 5-1 Canvas Geometry 



Scrollbars 




(C AN VAS_WI DTH 
CANVAS_HEK3HT 



The Canvas Think of the canvas itself as a logical surface on which you can draw. The width 

and height of the canvas are set via the attributes CANVAS_WIDTH and 
C ANVAS_HE I GHT . So the coordinate system is as shown in Figure 5-1, with the 
origin at the upper left comer and the point (CANVAS_WIDTH - 1, 
CANVAS_HEIGHT - 1) at the lower right comer. Note that the logical canvas 
origin is always at (0, 0). 

The Canvas Pixwin As mentioned above, you draw on the canvas by writing into the canvas pixwin, 

which is retrieved via the CANVAS_PIXWIN attribute or the 
canvas_pixwin( ) macro. 

The canvas pixwin is set up to take scrolling into account by performing the 
transformation from your canvas coordinate system to its pixwin coordinate sys- 
tem. So when you draw into the canvas pixwin using the pw_* functions you 
don’t have to do any mapping yourself — the arguments you give should be in 
the canvas coordinate system. 

Between the frame border and the canvas pixwin is a margin, set via the attribute 
CANVAS MARGIN. This margin defaults to zero pixels, so in the simple case, 
the canvas pixwin occupies the entire inner area of the window pixwin. If one or 
more scrollbars are present, the canvas margin begins at the inside border of the 
scrollbar. 

Note the distinction between the pixwin of the canvas (attribute 
CANVAS_PIXWIN) and the pixwin of the window (attribute WIN_PIXWIN). 

The canvas pixwin is one of several regions of the window’s pixwin, which also 
includes the regions occupied by the scrollbars and the margin. 

#sun Revision A, of March 27, 1990 
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5.4. Repainting 



Retained Canvases 



Non-Retained Canvases 



The Repaint Procedure 



The canvas package manages the canvas pixwin for you. In particular, the clip- 
ping list is restricted to the area of the canvas pixwin actually backed by the can- 
vas. This means that you can never draw off the edge of the canvas. For exam- 
ple, if you have set the canvas height to be less than the height of the canvas 
pixwin, any pw_* operations that attempt to draw below the canvas height will 
be clipped away. 

By default, canvases are retained — i.e. the canvas package maintains a copy of 
the bits on the screen in a backing pixrect, from which it automatically repaints 
the screen image when necessary. If you wish to handle repainting yourself, you 
can defeat this feature. 

The canvas package allocates a backing pixrect the size of the logical canvas. 
When the canvas width or height changes, a new backing pixrect of the proper 
dimensions is allocated, the contents of the old pixrect are copied into the new 
pixrect, and the old pixrect is freed. 

For a non-retained canvas, set CANVAS_RETAINED to FALSE, and give your 
own repaint function as the value of CANVAS_REPAlNT_PROC. 

The repaint procedure is called whenever some part of the canvas has to be 
repainted onto the canvas pixwin. Note that if you supply a repaint proc, it will 
be called even if the canvas is retained — i.e. the canvas package will not 
automatically copy from the backing pixrect to the canvas pixwin. 

The form of the repaint procedure is: 

sample_repa int_proc( canvas , pixwin, repaint_area) 

Canvas canvas; 

Pixwin *pixwin; 

Rectlist *repaint_area; 

The first two arguments are the canvas and its pixwin (i.e. the value of 
canvas_pixwin ( canvas ) ). The third argument, repaint_area, is a 
pointer to a list of rectangles (type Rectlist * ) which define the area to be 
painted . 22 

Before the canvas package calls your repaint procedure, it restricts the clipping 
list to the area which needs to be painted. Thus if your application is not capable 
of repainting arbitrary areas of the canvas you can repaint the entire image 
without worrying about excessive repainting. 

If you choose not to redraw each individual rect in the repaint area, you can use 
the rectangle given by repaint area - >rl_bound, which is the bounding 
rectangle for the repaint area. 

Note that if the attribute CANVAS_AUTO_CLEAR is TRUE, the canvas package 
will clear the repaint area before calling your repaint procedure. 

22 Rectlists are covered in detail in the chapter on Reds and Rectlists in the SunView System Programmer’ s 
Guide. 
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A retained canvas has two advantages. First, the repainting will be faster since it 
is a simple block copy operation. Second, it eliminates the need for the applica- 
tion to keep a display list from which to regenerate the image. 

On the other hand there is a performance penalty on writing, since each operation 
is performed both on the canvas pixwin and the backing pixrect. This penalty 
may be reduced by using the pw_batch( ) call described in the chapter entitled 
Imaging Facilities: Pixwins. 

The client’s resize procedure is called whenever the canvas width or height 
changes. Its form is: 

sample_resize_proc( canvas, width, height) 

Canvas canvas; 

int width; 

int height; 

NOTE You should never repaint the image in the resize procedure, since if there is any 
new area to be painted, the repaint procedure will be called later. 

There are some subtle points to be aware of related to whether or not the image is 
fixed size (CANVAS_FIXED_IMAGE is TRUE). In the default case the image is 
fixed size, and the repaint procedure will not be called when the canvas gets 
smaller, since there will be no new canvas area to be repainted. If the image is 
not fixed size, then whenever the canvas size changes, the canvas package 
assumes that the entire canvas needs to be repainted, and the repaint area will 
contain the entire canvas. 

Initializing a Canvas Neither the repaint procedure nor the resize procedure will be called until the 

canvas subwindow has been displayed at least once. This allows you to create 
and initialize a canvas without having to deal with the resize/repaint procedures. 
The very first time the canvas is displayed, the resize procedure will be called 
with the current canvas size. This initial call to the resize procedure allows you 
to synchronize with the canvas size. 



Retained vs. Non-Retained 



5.5. Tracking Changes in 
the Canvas Size 
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Example 3: 



The canvas in the program below has a repaint procedure which fills the canvas 
with an appropriately sized rectangle and diagonals. 



/******************★**************************************/ 
/* */ 

/* canvas_repaint . c */ 

/* */ 

/*********************************************************/ 
/*************★*******************************************/ 
/* */ 

/* This program draws a rectangular image which includes */ 

/* two diagonally drawn intersecting lines. */ 

/* */ 

/****★*****************★**************■********************/ 

tinclude <suntool/sunview .h> 
tinclude <suntool/canvas .h> 
static void repaint_canvas () ; 
main (argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 

frame = window_create (NULL, FRAME, 0); 
window_create (frame , CANVAS , 

CANVAS_RETAI NED , FALSE , 

CANVAS_F I XED_I MAGE , FALSE, 

CANVAS_REPAINT_PROC, repaint_canvas , 

0 ) ; 

window_main_loop (frame) ; 
exit (0) ; 

} 

static void 

repaint_canvas (canvas, pw, repaint_area) 

Canvas canvas; 

Pixwin *pw; 

Rectlist *repaint area; 



{ 



int width = (int) window_get (canvas, CANVAS_WIDTH) ; 
int height = (int) window_get (canvas, CANVAS_HEIGHT) ; 
int margin = 10; 
int xleft = margin; 
int xright = width - margin; 
int ytop = margin; 
int ybottom = height - margin; 

/* draw box */ 

pw_vector (pw, xleft, ytop, xright, ytop, PIX_SRC, 1); 
pw_vector (pw, xright, ytop, xright, ybottom, PIX_SRC, 1); 
pw_vector (pw, xright, ybottom, xleft, ybottom, PIX_SRC, 1); 
pw_vector (pw, xleft, ybottom, xleft, ytop, PIX_SRC, 1) ; 

/* draw diagonals */ 

pw_vector (pw, xleft, ytop, xright, ybottom, PIX_SRC, 1); 
pw_vector (pw, xright, ytop, xleft, ybottom, PIX_SRC, 1); 
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There are several points to note from the example on the previous page. First, 
since the width and height of the canvas are not specified, they default to the 
width and height of the window. Second, since the image being drawn is depen- 
dent on the size of the canvas, we set CANVAS_FIXED_IMAGE to FALSE. 
Third, when the repaint proc is called, we don’t bother to draw the specified 
repaint area, instead we rely on the clipping list to be restricted correctly and 
simply redraw the entire image. 

5.6. Automatic Sizing of Two attributes requiring some explanation are CANVAS_auto_expand and 
the Canvas CANVAS_auto_SHRINK. Setting both these attributes to true allows you to 

have a drawing area which automatically tracks the size of the window. 

If CANVAS_AUTO_EXPAND is TRUE, the canvas width and height are never 
allowed to be less than the edges of the canvas pixwin. For example, if you try to 
set CANVAS _WIDTH to a value which is smaller than the width of the canvas 
pixwin, the value will be automatically expanded (rounded up) to the width of 
the canvas pixwin. 

The main use of CANVAS_AUTO_EXPAND is to allow the canvas to grow bigger 
as the user stretches the window. For example, if the canvas starts out exactly 
the same size as the canvas pixwin, and the user stretches the window, the canvas 
pixwin will get bigger, which will cause the canvas itself to expand. 

Another point to keep in mind is that whenever you set 

CANVAS_AUTO_EXPAND to TRUE, the canvas will be expanded to the edges of 
the canvas pixwin (if it is smaller to begin with). 

CANVAS_AUTO_SHRINK is symmetrical to CANVAS_AUTO_EXPAND. If 
CANVAS_AUTO_SHRiNK is TRUE, the canvas width and height are never 
allowed to be greater than the edges of the canvas pixwin. 

NOTE As described in Section 4.8, Attribute Ordering, the canvas attributes are 

evaluated before the generic window attributes. This means that, if you want to 
set the window size and then disable automatic sizing of the canvas, you must 
first set the window size, then, in a separate window_set ( ) call, disable 
CANVAS_AUTO_SHRINK and/or CANVAS_AUTO_EXPAND. If you do both in 
the same call, the auto-sizing will be turned off before the window size is set, so 
the canvas size will not match the window size you specify. Here is an example 
of how to do it correctly: 



canvas = window_create (frame, CANVAS, 

WIN_HEIGHT, 400, 

WIN__WIDTH, 600, 

0 ); 

window_set ( canvas, 

CANVAS__AUTO_SHRINK, FALSE, 

CANVAS_AUTO_EXP AND , FALSE, 

0 ); 

< ) 
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5.7. Handling Input in 
Canvases 



This section gives some hints on basic handling of input in canvases . 23 



Default Input Mask By default, canvases enable L0C_WINENTER, L0C_WINEXIT, LOC_MOVE and 

the three mouse buttons, MS_LEFT, MS_MIDDLE and MS_RIGHT 24 



NOTE Since the canvas pixwin is actually a region of the subwindow’s pixwin, your 
event procedure will receive loc_RGNENTEr and loc_rgnexit events 
rather than LOC_WINENTER and L0C_WINEXIT. The locator motion events 
— LOC_MOVE, LOC_STILL, LOC_DRAG, and LOC_TRAJECTORY — will 
only be passed to your event procedure if they fall within the canvas pixwin. 

You can enable events other than those listed above with the window attributes 
applying to events. So, for example, you could allow the user to type in text to a 
canvas by calling: 



window_set ( canvas, WIN_CONSUME_KBD_EVENT , WIN_ASCI I_EVENTS , 0); 

l J 



An application needing to track mouse motion with the button down would 
enable LOC_DRAG by calling: 



window_set( canvas, WIN_CONSUME_PICK_EVENT , LOC_DRAG , 0); 
v J 



If you supply an event procedure as the value of WlN_EVENT_PROC, it will get 
called when any event is received for the canvas. Before your event procedure 
gets called, however, the canvas package does some processing. If the event is 
WIN_REPAINT or WIN_RESI ze, the canvas package calls your repaint or 
resize procedures if necessary. If the event is SCROLL_REQUEST, then the can- 
vas package performs the scroll . 25 The repaint, resize and scroll events are then 
passed to your event procedure. In the case of events which have x-y coordi- 
nates, the canvas package translates the events from the coordinate space of the 
canvas pixwin to that of the logical canvas. 

Translating Events from Functions are provided to translate event coordinates from the coordinate space 

Canvas to Window Space of the canvas to the coordinate space of the canvas subwindow, and vice versa. 

To go from canvas space to window space, use canvas_window_event ( ) . 
Keep in mind that the canvas_window_event function changes fields in its 
event argument structure. For example, if you want to put up a menu in a canvas 

23 The general input paradigm for Sunview is discussed in Chapter 6, Handling Input. See that chapter for a 
fall discussion of the available input events and how to use them. 

24 Note that the canvas package expects to receive these events, and will not function properly if you disable 
them. Also, if the user has the enabled the Left_Handed option in the Input category of def aultsedit(l), 
the mouse buttons are reversed: MS LEFT refers to the right mouse button, MS RIGHT to the left mouse 
button. 

25 If you want write a procedure which is called before the repaint, resize or scroll event is processed by the 
canvas package, in order to modify the interpretation of the event, you must interpose on the event, as described 
in Chapter 17, The Notifier . 
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Border Highlighting 



Example 4: 



subwindow, you need to specify the menu’s location in the coordinate of the 
subwindow, not of the canvas. 

To go from window space to canvas space, use canvas_event ( ) . This 
returns the Event * it is passed, with the x and y fields changed. The transla- 
tion is necessary if you read your own events with window__read_event ( ) , 
described in the next chapter, Handling Input. 

The SunView convention is that a subwindow indicates that it is accepting key- 
board events by highlighted its border. By default, canvas subwindows do not 
enable any keyboard events, so the border is not highlighted. However, if you 
explicitly enable keyboard events, by consuming WIN_ASCII_EVENTS, the 
canvas package will highlight the canvas border when it is given the input focus. 



The program below prints out the corresponding string when the user types 0,1, 
or 2 into its canvas: 




/* */ 

/* canvas_input . c */ 

/* */ 

/* */ 

/* This program draws a blank canvas */ 

/* ... and nothing more. */ 

/* */ 



f-k-k-k-k-k-k'k-k-k'k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-kick-k-k-k-k-k-k-k-k'k j 

linclude <suntool/sunview.h> 
tinclude <suntool/canvas .h> 
static void my_event_j?roc ( ) ; 
main(argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 

frame = window_create (NULL, FRAME, 0); 
window_create (frame, CANVAS, 

W I N_CON SUME_KBD_E VENT , WIN_ASC I I_EVENT S , 
WIN_EVENT_PROC , my_e vent_pr oc , 

o); 

window_main_loop (frame) ; 
exit (0) ; 

} 

static void 

my_event_proc (canvas, event) 

Canvas canvas; 

Event *event; 

{ 

char *string = NULL; 
switch (event_action (event ) ) { 

case ' 0' : 
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5.8. Color in Canvases You can use color in canvases by specifying a colormap segment for the canvas 

with the colormap manipulation routines described in Chapter 6, Handling Input. 

Setting the Colormap Segment The first thing to note is that since the canvas pixwin is a region of the 

WIN_PIXWIN, you must also set the colormap segment for the canvas pixwin. 

Color in Retained Canvases If the canvas is retained, then the colormap segment must be set before 

CANVAS_RETAINED is set to TRUE. This is because the canvas package will 
determine the depth of the backing pixrect based on depth of the colormap seg- 
ment defined for the WIN_PIXWIN. (If the colormap segment depth is greater 
than two, then the full depth of the display will be used. Otherwise, the backing 
pixrect depth will be set to one.) 

Since the depth of the backing pixrect is determined when the canvas is created, 
you must create the canvas with CANVAS_RETAINED FALSE, then set the 
colormap segment, then set CANVAS_RETAINED to TRUE. 

Color in Scrollable Canvases If the canvas has scrollbars, you need to attach the scrollbars to the canvas after 

the colormap segment has been changed. If the canvas has already been created 
with scrollbars attached, you should change the colormap, then re-attach the 
scrollbars. This will insure that the scrollbar pixwin regions use the new color- 
map segment. 
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Below is an example of setting the colormap segment for a canvas: 



#include <suntool/sunview . h> 
#include <suntool/canvas . h> 
#include <sunwindow/cms_rainbow. h> 



init_color_canvas (base_f rame) 
Frame baseframe; 



{ 



Canvas 

Pixwin 

unsigned char 
unsigned char 
unsigned char 



canvas ; 

*pw; 

red [CMS_RAINBOWSIZE] ; 
green [CMS_RAINBOWSIZE] ; 
blue [ CMS_RAINBOWSI ZE] ; 



canvas = window_create (base_frame, CANVAS, 
CANVAS_RETAINED, FALSE, 

0 ); 

cms_rainbowsetup(red, green, blue); 

/* set the WIN_PIXWIN colormap */ 

pw = (Pixwin *) window_get( canvas, WIN_PIXWIN) ; 

pw_setcmsname(pw, CMS_RA INBOW) ; 

pw_putcolormap (pw, 0, CMS_RAINBOWSIZE, red, green, blue); 

/* set the CANVAS_PIXWIN colormap */ 
pw = (Pixwin *) canvas_pixwin (canvas) ; 
pw_setcmsname (pw, CMS_RAINBOW) ; 

pw_putcolormap (pw, 0, CMS_RAINBOWSIZE, red, green, blue); 

window_set ( canvas , 

CANVAS_RETAINED, TRUE, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create ( 0 ) , 
WIN_HORI ZONTAL_SCROLLBAR , scrollbar_create ( 0 ) , 

0 ); 

} 

1 
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Handling Input 



Material Covered This chapter explains how input is handled in SunView. Specifically it: 

□ gives an overview on how input is handled in SunView 

□ describes events and how they are used; 

□ gives various classes of events — ASCII, action events, function keys, locator 
buttons, locator motion, window generated events, and so on; 

□ explains the input focus model distinguishing between pick and keyboard 
focuses; 

□ shows how to control where input is distributed using input masks ; 
a shows how to query the state of an event; 

□ shows how to explicitly read events. 

The material in this chapter applies to the window system as a whole. However, 
it is of special interest to alerts or clients of canvases, who typically will want to 
handle events themselves. 

Header Files The definitions necessary to use SunView's input facilities are in the header file 

<sunwindow/win_input . h>, which is included by 
<sunwindow/window_hs . h>, which in turn is included by default when 
you include <suntool/sunview. h>. 

Related Documentation The chapter titled Workstations in the SunView System Programmer’ s Guide 

explains the input system at a lower level, covering such topics as how to add 
user input devices to SunView. 

Summary Listing and Tables To give you a feeling for what you can do with events, a list of the available 

event descriptors and input related window events is given on the following page. 
Many of these are discussed in the rest of this chapter and elsewhere (use the 
Index to check). All are briefly described with their arguments in the input sum- 
mary tables in Chapter 19, SunView Interface Summary: 

□ the Event Descriptors, 

□ the Input-Related Window Attributes. 
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Input-Related Window Attributes 


WIN_INPUT_DESIGNEE 


WIN_CONSUME_KBD_EVENTS 


WIN GRAB ALL INPUT 


WIN_IGNORE_KBD_EVENTS 


WIN_KBD_FOCUS 


WIN_CONSUME_PICK_EVENT 


WIN KBD INPUT MASK 


WIN_IGNORE_PICK_EVENT 


WIN PICK INPUT MASK 


WIN_CONSUME_P ICK_EVENTS 


WIN_CONSUME_KBD_EVENT 

WIN_IGNORE_KBD_EVENT 


WIN_IGNORE_PICK_EVENTS 



Event Descriptors 


WIN_ 


_NO_EVENTS 




WIN_RIGHT_KEYS 


WIN_ 


_ASCII_EVENTS 




WIN_TOP_KEYS 


WIN_ 


IN TRANSIT EVENT S 




WIN_UP_ASCII_EVENTS 


WIN_ 


_LEFT_KEYS 




WIN_UP_EVENTS 


WIN_ 


_MOUSE_BUTTONS 
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6.1. An Overview of the The input environment for Sun View differs from UNIX programs. Most UNIX 

Input Environment programs read characters from standard input by using either the read(2) system 

call or the standard I/O functions such as getc(3S), gets(3S), or scanf (3S). 
SunView is different in that the underlying Notifier formats user input into uni- 
form events, which it distributes to the window’s event procedure. 



How are events generated ? 



Figure 6-1 illustrates how events are generated and handled in SunView. 



Figure 6-1 Input Events 
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Events are generated from several sources. These include standard devices such 
as the keyboard and mouse, special input devices such as graphics tablets, and 
the window system itself. 

SunView does not directly receive events from the hardware devices. Instead 
each user action is interpreted by a “virtual” user input device ( VUID) interface. 
This interface packages the data it receives into an event and sends it to the appli- 
cation process. 26 

What does the Notifier do with The Notifier weaves events from all of these sources into a single, ordered event 

these events ? stream. This event stream eliminates the need for the application to poll separate 

streams from the different devices. 

Because the underlying Notifier multiplexes the input stream between windows, 
each individual window operates under the illusion that it has the user’s full 
attention. That is, it sees precisely those input events that the user has directed to 
it. 

How do windows determine Each window indicates which events it is prepared to handle using input masks, 

which input they will receive? described in Section 6.6, Controlling Input in a Window. These masks only let 

specified events through to the process. 



6.2. Events As discussed in the previous section, each user action generates an input event. 

This event is passed to your event procedure as an Event pointer (type 
Event *). Three types of information are encoded as part of an event: 

□ an identifying code, accessed with the macro event_action ( ) 

o the location of the event in the window’s coordinate system, accessed with 
the macros event_x ( ) and event_y ( ) 

□ a timestamp, accessed with the macro event_time ( ) 

Notice that the macro event_action ( ) has replaced the old event_id( ) . 
For compatibility reasons, event id ( ) is still supported, so that old code that 
does not use the new action event codes will still work. See Section 6.4, Classes 
of Events, for an explanation of action events. New programs that want to take 
advantage of the new action events must use the event_action ( ) macro. 

An event Procedure Use the following form to specify an an event procedure in your applications: 

void 

sample_event_proc( window, event, arg) 

Window window; 

Event * event; 

caddr_t arg; 



26 It is possible to bypass the VUID and receive unencoded events. Refer to the section on Unencoded Input 
in Chapter 7 of the SunView System Programmer’ s Guide. 
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How Subwindows Handle 
Events 



6.3. A List of Events 



The arguments passed in are the window, the event, and an optional argument 
containing data pertaining to the event. For example, if the event is a 
SCROLL_REQUEST, arg will be the scrollbar that sent the event. 

The canvas and panel subwindows pass events that they receive on to an event 
procedure. These event procedures are supplied by the application as the value 
of WIN_EVENT_PROC. If you set the WlN_EVENT_PROC of a canvas or panel 
to a function you have written, you can receive events after they have been pro- 
cessed by the canvas or panel. Both the canvas and panel packages process 
SCROLL_REQUEST, WIN_RESIZE, and WIN_REPAINT events before calling 
your event procedure. The form of an event procedure is: 

void 

sample_event_proc (window, event, arg) 

Window window; 

Event * event; 

caddr_t arg; 

The default panel event procedure maps events to actions and determines which 
panel item to send the event to. The default canvas event procedure does no 
further processing of the event. You can call the default window event procedure 
by calling window_def ault_event_proc( ) with the same arguments 
passed to your event procedure. 27 

Two tables are given on the following pages. Table 6-1, Event Codes, lists the 
predefined event codes and their values. 28 The event id or code numbers that the 
window system uses to represent an event are included in this table. These event 
code numbers are in the range of 0-65535. The numbers are useful when debug- 
ging a program because the debugger reports event codes as decimal integers and 
not as names. 

Table 6-2, Keyboard Motions and Accelerators, lists the event name and its asso- 
ciated keyboard accelerator. 



27 If you need to receive an event before it is processed by a canvas, panel, or any other type of window, you 
can use the more general notifier interposition mechanism described in Chapter 17, The Notifier, 

28 The same table also appears in the input summary section of Chapter 1 9, SunView Interface Summary. 
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Table 6-1 Event Codes 



Event Code 


Description 


Value (for debugging) 


ASCI I_FIRST 


Marks beginning of ASCII range 


0 


ASCI I_LAST 


Marks end of ASCII range 


127 


METAFIRST 


Marks beginning of META range 


128 


METALAST 


Marks end of META range 


255 


AC T I ONERAS E__CHAR_BACKWARD 


Erase char to the left of caret 


31745 


ACTI ON_ERASE_CHARJFORWARD 


Erase char to the right of caret 


31746 


AC T I ONERAS E_WORD_BACKWARD 


Erase word to the left of caret 


31747 


ACTI ON_ERASE_WORD_FORWARD 


Erase word to the right of caret 


31748 


ACTION_ERASE_LINE_BACKWARD 


Erase to the beginning of the line 


31749 


ACTION_ERASE_LINE_END 


Erase to the end of the line 


31750 


ACTION_GO_CHAR_BACKWARD 


Move the caret one character to the left 


31752 


ACTI ON_GO_CHAR_FORWARD 


Move the caret one character to the right 


31753 


ACTION_GO_WORD_BACKWARD 


Move the caret one word to the left 


31754 


ACTI ON_GO_WORD_END 


Move the caret to the end of the word 


31756 


ACTION_GO_WORD_FORWARD 


Move the caret one word to the right 


31755 


ACTI ON_GO_LI NE_BACKWARD 


Move the caret to the start of the line 


31757 


ACTI ON_GO_L I NE_END 


Move the caret to the end of the line 


31759 


ACTI 0N_GO_LI NE_FORWARD 


Move the caret to the start of the next line 


31758 


ACTI ON_GO_COLUMN_B ACKW ARD 


Move the caret up one line, 
maintaining column position 


31761 


ACTI ON_GO_COLUMN_FORWARD 


Move the caret down one line, 
maintaining column position 


31762 


ACTI ON_GO_DOCUMENT_START 


Move the caret to the beginning of the text 


31763 


ACTI ON_GO_DOCUMENT_END 


Move the caret to the end of the text 


31764 


ACTION_STOP 


Stop the operation 


31767 


ACTION_AGAIN 


Repeat previous operation 


31768 


ACT I ON_PROPS 


Show property sheet window 


31769 


ACT I ON_UNDO 


Undo previous operation 


31770 


ACTION FRONT 


Bring window to the front of the desktop 


31772 


ACT I ONB ACK 


Put the window at the back of the desktop 


31773 


ACTION_OPEN 


Open a window from its icon form or close 
if already open) 


31775 


ACTION_CLOSE 


Close a window to an icon 


31776 


ACT I ONCOP Y 


Copy the selection to the clipboard 


31774 


ACTION_PASTE 


Copy clipboard contents to the insertion point 


31777 


ACTION_CUT 


Delete the selection, put on clipboard 


31781 


ACTI ON__COPY_THEN_PASTE 


Copies then pastes text 


31784 


ACTION_FIND_FORWARD 


Find the text selection to the right of the caret 


31779 


ACTI ON_F I ND_B ACKWARD 


Find the text selection to the left of the caret 


31778 


AC I I ON_FIND_AND_REPLACE 


Show find and replace window 


31780 


ACTION_SELECT_FIELD_FORWARD 


Select the next delimited field 


31783 


ACTI ON_SELEC T_FI ELD_BACKW ARD 


Select the previous delimited field 


31782 
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Table 6-1 Event Codes — Continued 



Event Code 


Description 


Value (for debugging) 


ACTION_MATCH_DELIMITER 


Selects text up to a matching delimiter 


31894 


ACTION_QUOTE 


Causes next event in the input stream to 
pass untranslated by the keymapping system 


31898 


ACTION_EMPTY 


Causes the subwindow to be emptied 


31899 


ACTIONSTORE 


Stores the specified selection as a new file 


31785 


ACTION_LOAD 


Loads the specified selection as a new file 


31786 


ACTION_GET_FILENAME 


Gets the selected filename 


31788 


ACTIONSETDI RECTORY 


Sets the directory to the selection 


31788 


AC T I ON_ I NCLUDE_F I LE 


Selects the current line (in pending-delete mode) 
and attempts to insert the file described by that selection 


31891 


ACTION_CAPS_LOCK 


Toggle caps lock state 


31895 


PANEL_EVENT_CANCEL 


The panel or panel item is no longer “current” 


32000 


PANEL_EVENT_MOVE_IN 


The panel or panel item was entered 
with no mouse buttons down 


32001 


PANEL_EVENT_DRAG_IN 


The panel or panel item was entered with one or more 
mouse buttons down 


32002 


SCROLL_REQUEST 


Scrolling has been requested 


32256 


SCROLL_ENTER 


Locator (mouse) has moved into the scrollbar 


32257 


SCROLL_EXIT 


Locator (mouse) has moved out of the scrollbar 


32258 


LOC_MOVE 


Locator (mouse) has moved 


32512 


LOC_STILL 


Locator (mouse) has been still for 1/5 second 


32513 


LOC_WINENTER 


Locator (mouse) has entered window 


32514 


LOC_WINEXIT 


Locator (mouse) has exited window 


32515 


LOC DRAG 


Locator (mouse) has moved while a button was down 


32516 


LOC_RGNENTER 


Locator (mouse) has entered a region of the window 


32519 


LOC_RGNEXIT 


Locator (mouse) has exited a region of the window 


32520 


LOC_TRAJECTORY 


Inhibits the collapse of mouse motions; clients receive 
LOC TRAJECTORY events for every locator motion 
the window system detects. 


32523 


WIN_REPAINT 


Some portion of window requires repainting 


32517 


WIN_RESIZE 


Window has been resized 


32518 


WIN_STOP 


User has pressed the stop key 


32522 


KBD REQUEST 


Window is about to become the focus of keyboard input 


32526 


KBD_USE 


Window is now the focus of keyboard input 


32524 


KBD_DONE 


Window is no longer the focus of keyboard input 


32525 


SHIFT_LEFT 


Left shift key changed state 


32530 


SHIFT_RIGHT 


Right shift key changed state 


32531 


SHIFT_CTRL 


Control key changed state 


32532 


SHIFT_META 


Meta key changed state 


32534 


SHIFT_LOCK 


Shift lock key changed state 


32529 


SHIFT_CAPSLOCK 


Caps lock key changed state 


32528 
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Table 6-1 


Event Codes — Continued 




Event Code 


Description 


Value (for debugging) 


BUT ( i ) 




Locator (mouse) buttons 1-10 


BUT(l) is 32544 


MS_LEFT 




Left mouse button 


32544 


MS_MIDDLE 




Middle mouse button 


32545 


MS_RIGHT 




Right mouse button 


32546 


KEY_LEFT ( i ) 




Left function keys 1-15 


KEY LEFT ( 1 ) is 32554 


KEY_RIGHT(i) 




Right function keys 1-15 


KEY RIGHT ( 1 ) is 32570 


KEY_TOP ( i ) 




Top function keys 1-15 


KEY_TOP ( 1 ) is 32586 
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Table 6-2 Keyboard Motions and Accelerators 



Command Token 


S unView 4.0 


SunView 3.x 


ACT ION_ERASE_CHAR_BACKWARD 


[ Delete ) 


( Delete ) 


ACT ION_ERASE_CHAR_FORWARD 


1 Shift-Delete ] 


[ Shift-Delete ] 


ACTION_ERASE_WORD_BACKWARD 


[ Control -W ] 


[ Control-W 1 


ACT ION_ERASE_WORD_FORWARD 


f Shift-Con trol-W ] 


f Shift-Control W ] 


ACTION_ERASE_LINE_BACKWARD 


[ Control -U ) 


1 Control-U ) 


ACT ION_ERASE_LINE_END 


( Shift-Control -U ) 


[ Shift-Control-U ] 


ACT ION_GO_CHAR_BACKWARD 


i Control-B ] or [ Shift-Control-F 1 or 
(RIO) 




ACTION_GO_CHAR_FORWARD 


[ Control-F ) or f Shift-Control-B ) or 
( R12 ] 




ACT ION_GO_WORD_BACKWARD 


[ Control-comma ] or 
[ Shift -Control-pcnW J or 
1 Shift-Control -s/as/? ) 




ACT ION_GO_WORD_END 


[ Control-period } 




ACTION GO WORD FORWARD 


[ Control-s/asA ] or 






[ Shift-Control-comma ) 




ACTION_GO_LINE_FORWARD 


( Control-semicolon ) or ( R1 1 ) 




ACTION_GO_LINE_BACKWARD 


l Control-A ) or [ Shift-Control-E ] 




ACTION_GO_LINE_END 


[ Control-E ) or [ Shift-Control-A ] 




ACTION GO COLUMN BACKWARD 


[ Control-P ] or [ Shift-Control-N 1 or 






[ RIO J 




ACT ION_GO_COLUMN_FORWARD 


I Control-N ) or [ Shift-Control-P ) or 
[R12] 




ACT ION_GO_DOCUMENT_ST ART 


[ Shift-Control -Return ] or f R7 ) 




ACTION GO_DOCUMENT END 


[ Control-Return 1 or 1 R 1 3 ] 


[ Control-Retum ) 


ACTION_STOP 


rm 


rm 


ACTION_AGAIN 


fL2l or f Meta-A ] 


rm 


ACTION_PROPS 


(TD 


rm 


ACTION_UNDO 


fL4l or 1 Meta-U 1 


rm 


ACT ION_FRONT 


rui 


rm 


ACTION BACK 


[ Shift-L5 ] 


[ Shift-L5 1 


ACT ION_OPEN 


rm 


rm 


ACT ION_CLOSE 


[ Shift-L7 1 


rShift-L7 ] 


ACT ION_COPY 


fL6l or f Meta-C ) 


rm 


ACT ION_PASTE 


rt8l or [ Meta-V } 


!m or [ Control-G ] 


ACTIONCUT 


( L10 ) or 1 Meta-X ) 


[ L10 ) or [ Control-D 1 


ACT ION_COPY_THEN_PASTE 


[ Meta- P ) 


! Control-P ] 


AC T I ON_F I NDFORWARD 


rm or I Meta-F ) 


[ L9 ) or [ Control-F ] 


ACT I ON_F I NDBACKWARD 


( Shift-L9 1 or ( Shift-A/cta-F ) 


( Shift-L9 tor [ Shift-Control-F ] 


ACTION_FIND_AND_REPLACE 


l Control -L9 ) 




ACT ION_SELECT_FI ELD_FORWARD 


( Control -Tab j 




ACT ION_SELECT_FIELD_BACKWARD 


! Shift-Control -Tab ) 




ACTION_MATCH_DELIMITER 


[ Meta-D ) 




ACTION_QUOTE 


[ Meta-Q ) 




ACT ION_EMPTY (Document) 


[ Meta- E ] 




ACTION_STORE 


[ Meta-S ] 
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Table 6-2 


Keyboard Motions and Accelerators — Continued 




Command Token 


SunView 4.0 


SunView 3.x 


ACTIONLOAD 


! Meta-L i 




ACTION_INCLUDE_FILE 


! Meta-l ) 




ACTIONHELP 29 






ACT ION GET_FI LENAME 


[ Escape ] 


[ Escape ] 


ACT IONCAPSLOCK 


(TD 


CtD 



6.4. Classes of Events 



ASCII Events 



Locator Button Events 



Locator Motion Events 



This section groups each of the events described in Table 6-1, Event Codes , into 
logical classes. Each class is described below. 

The event codes in the range 0 to 255 inclusive are assigned to the ASCII event 
class. This includes the standard 7-bit ASCII codes and their 8-bit META coun- 
terparts. 

If a user strikes a key which has an obvious ASCII meaning; that is, a key in the 
main typing array labeled with a single letter, it causes the VUID to enqueue for 
the appropriate window an event whose code is the corresponding 7-bit ASCII 
character. 

The META event code values (128 through 255) are generated when the user 
strikes a key that would generate a 7-bit ASCII code while the META key is also 
depressed. 

The standard Sun locator is a three button mouse, whose buttons generate the 
event codes MS_LEFT, MS_MIDDLE and MS_RIGHT. 

In general, a physical locator can have up to 10 buttons connected to it. In some 
cases, the locator itself may not have any buttons on it; however, it may have 
buttons from another device assigned to it. A light pen is an example of such a 
locator. 

Each button that is associated with the VUID's locator is assigned an event code; 
the i-th button is assigned the code BUT ( i ) . Thus the event codes MS_LEFT, 
MS_MIDDLE and MS_RIGHT correspond to BUT ( 1 ) , BUT ( 2 ) and BUT ( 3 ) . 

The physical locator constantly provides an (x, y) coordinate position in pixels; 
this position is transformed by SunView to the coordinate system of the window 
receiving an event. Locator motion event codes include LOC MOVE, 
LOC_DRAG, LOC_TRAJECTORY, and LOC_STILL. 

Since the locator tracking mechanism reports the current position at a set sam- 
pling rate, 40 times per second, fast motions will yield non-adjacent locations in 
consecutive events. 



29 If your keyboard has the [ L16 ] key, you may also use it. 
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Window Events 



Resize & Repaint Events 



A LOC_MOVE event is reported when the locator moves, regardless of the state 
of the locator buttons. If you only want to know about locator motion when a 
button is down, then enable LOC_DRAG instead of LOC_MOVE. This will 
greatly reduce the number of motion events that your application has to process. 

When you enable LOC_MOVE or LOC_DRAG, the window system gives you the 
current locator position by collapsing consecutive locator motion events into one. 
This operation is appropriate for applications such as dragging an image from 
one point to another, in which it is important to keep up with the mouse cursor. 

For some applications, however, each point on the cursor trajectory is of interest; 
for example, a program that lets the user draw. In these situations you may not 
want to collapse consecutive motion events. In such a situation you should ask 
for LOC_TRAJECTORY events, which suppresses any event collapsing so that 
you get all the locator movements that the window system sees. 

Note that when you ask for LOC_TRAJECTORY events, you get (many!) 
LOC_TRAJECTORY events in place of LOC_MOVE’s, but you still get 
LOC_DRAG events if you have enabled them. 

If you ask for LOC_STlLL, a single L0C_STILL event will be reported after 
the locator has been still for 1/5 of a second. 



Window events are generated by the window system itself. They are meaningful 
only to the window to which they are directed. 

To be informed when the locator enters or exits a window, enable events with the 
codes LOC_WINENTER and LOC_WINEXIT. 

NOTE If you are using the tile mechanism described in the SunView System 

Programmer's Guide, then you will be told when the locator has entered or 
exited a tile using the LOC_RGNENTER and LOC_RGNEXlT events. To receive 
these events you must also have LOC_MOVE enabled. 

When the size of a window is changed (either by the user or programmatically) a 
WIN_RESI ZE event is generated to give the client a chance to adjust any 
relevant internal state to the new window size. You should not repaint the screen 
on receiving a resize event. You will receive a separate WIN REPAINT event 
when a portion of the window needs to be repainted. 

NOTE If you are using a canvas subwindow you will not need to track resize and 

repaint events directly. The canvas package receives these events, computes the 
new window dimensions or the precise area requiring repainting, and calls your 
resize or repaint procedures directly. See Chapter 5, Canvases for more details. 
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Keyboard Focus Events 



Stop Event 



Function Key Events 



Three events let your application interact with the keyboard focus mechanism 
(the keyboard focus is explained in section 6.6, Controlling Input in a Window ). 
When the user explicitly directs the keyboard focus towards your window, you 
will receive a KBD_REQUEST event. Your window will then become the key- 
board focus unless you call window_ref use_kbd_f ocus ( ) . Refusing the 
keyboard focus, when you don’t need it, contributes to the usefulness of the split 
keyboard/pick focus mode available as a runtime option to sunview(l). 

The events KBD_USE and KBD_DONE parallel the locator events 
LOC_WlNENTER and L0C_WINEXIT, respectively. KBD_USE indicates that 
your window now has the keyboard focus and KBD DONE indicates that your 
window no longer has it. 

If the user presses and releases the ( Stop 1 key, an event with the code 
WIN_STOP will be sent to the window under the cursor. 30 In addition, a 
SIGURG signal is sent to the window’s process. Your application can use the 
1 Stop 1 key by clearing a stop flag and setting a SIGURG interrupt handler 31 
before entering a section of code that might, from the user’s perspective, take a 
long time. If your SIGURG handler is called, set the stop flag and return. In the 
code that is taking a long time, query the stop flag whenever convenient. When 
you notice that the stop flag has been set, read the event, then gracefully ter- 
minate your long operation. 

The function keys in the VUID define an idealized standard layout that groups 
keys by location: 15 left, 15 right, 15 top and 2 bottom. 32 

The event codes associated with the function keys are KEY_LEFT ( i ) , 
KEY_RIGHT ( i ) and KEY_TOP ( i ) , where i ranges from 1 to 15. 

If you specifically ask for a function key event code, then that event code will be 
passed to your event procedure. 

If you don’t specifically ask for a given function key event code, then when the 
user presses that function key you will get an escape sequence instead of the 
function key event code (assuming ASCII events have been enabled). For physi- 
cal keystations that are mapped to cursor control keys, events with codes that 
correspond to the ANSI X3.64 7-bit ASCII encoding for the cursor control func- 
tion are transmitted. For physical keystations mapped to other function keys, 
events with codes that correspond to an ANSI X3.64 user-definable escape 
sequence are transmitted. 



30 WIN_STOP only works when enabled in the PICK event mask and not in the KBD event mask. 

31 See notify_set_signal_func( ) in in Chapter 17, TheNotifier 

32 The actual position of the function keys on a given physical keyboard may differ — see kbd(5) for details 
on various keyboards. 
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Shift Key Events 



Semantic Events 



Other Events 



Applications can notice when a shift key changes state by enabling events with 
the following codes: shift_left, shift_right, shift_ctrl, 
SHIFT_META, SHIFT_L0CK and SHIFT CAPSLOCK. Although these codes 
allow you to treat one or more shift key as function-invoking keys, this is not 
recommended. Instead of watching for the event directly, you should query the 
state of the shift keys via the macros described on the next page. 

Release 4.0 of the SunOS introduces a new type of event. These events are 
called action events and represent some old and many new functions in the win- 
dow system. They are similar to the old events in that they are mapped to 
specific keys on the keyboard. That is, certain combinations of keystrokes in 
SunView correspond to high-level action events. For example, pressing the 
f Copy ] key copies the current selection to the Clipboard in text subwindows, 
panels and tty subwindows. 

Action events differ from the old events in that applications can directly express 
interest in the high-level action, “Copy the selection to the Clipboard” rather than 
in the low-level, “The L6 key was pushed”. These events appear in Table 6-1 
with the prefix ACTI0N_. Applications should use action events, because left- 
handed users can assign 1 Copy 1 to a different key, and in the future users will be 
allowed to tie high-level events to arbitrary key combinations. 

Your application may receive events which don’t fall into any of the classes 
described above. For example, a non-standard input device, such as a second 
mouse, may emit its own types of events. Also, a software object may communi- 
cate with other software objects via events, as is the case when a scrollbar sends a 
SCROLL_REQUEST to a panel or a canvas. 

In general, your event procedure should not treat such unexpected events as 
errors. They can simply be ignored. 
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6.5. Event Descriptors Events have been further grouped into descriptors. Descriptors describe classes 

of events such as all ASCII events, all mouse buttons, all top function keys, and 
so on. You will use these descriptors to set input masks, described in Section 6.7 
Enabling and Disabling Events 

The descriptors are summarized in the following table. 

Table 6-3 Event Descriptors 



Event Descriptor 


Explanation 


WIN_NO_EVENTS 


Clears input mask — no events will be accepted. Note: the 
effect is the same whether used with a consume or an 
ignore attribute. A new window has a cleared input mask. 


WIN_ASCII_EVENTS 


All ASCfl events. ASCII events that occur while the META 
key is depressed are reported with codes in the META range. 
In addition, cursor control keys and function keys are 
reported as ANSI escape sequences: a sequence of events 
whose codes are ASCII characters, beginning with <ESC>. 


WIN_IN_TRANSIT_EVENTS 


Enables immediate LOC_MOVE, LOC_W IN ENTER, and 
LOC WINEX IT events. Pick mask only. Off by default. 


WIN_LEFT_KEYS 


The left function keys, KEY_LEFT(1) — KEY_LEFT(15). 


WIN_MOUSE_BUTTONS 


All of MS_R IGHT,MS_MI DOLE and MS_LEFT. 
Also sets or resets WIN_UP_EVENTS. 


WIN_RIGHT_KEYS 


The right function keys, KEY_RIGHT(1) — KEY_RIGHT(15). 


WIN_TOP_KEYS 


The top function keys, KEY_TOP(l) — KEY_TOP(15). 


WIN _UP_ASCI I_EVENTS 


Causes the matching up transitions to normal 
ASCH events to be reported — if you see an ’a’ 
go down, you’ll eventually see the matching ’a’ up. 


WIN_UP_EVENTS 


Causes up transitions to be reported for button 
and function key events being consumed. 



6.6. Controlling Input in a Input may be controlled using input focus and input mask. The input focus is the 

Window window that is currently receiving input. The input mask specifies which events 

a window will receive and which events a window will ignore. This section 
introduces these concepts and gives the algorithm used by the window system to 
decide which window will receive a given input. 
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Input Focus SunView supports two types of focus models, a single focus model and a split 

focus model. 

The single focus model specifies that all input, no matter which input device it 
came from, goes to the same window. The split input focus lets the user control 
the pick input focus and the keyboard input focus separately. 

The word pick comes from the general graphics term pick device, which is a user 
input device that allows you to move a cursor on the screen and then click a but- 
ton to choose a point on the screen. The most common pick devices are the 
mouse, light pen and graphics tablet. 

Under the split input focus model, mouse clicks and keystrokes may be distri- 
buted to different windows. This makes some operations easier for the user. For 
example, the user can select text in one window and move it to another window 
without having to position the cursor over the destination window. 

In general, the user controls the keyboard focus by using specific button clicks 
and controls the pick focus by moving the mouse. Sometimes, it is appropriate 
for input focuses to be under program control. Generally you should only change 
an input focus based on some explicit and predictable user action. 

You can indicate that you want a window to become the keyboard focus by set- 
ting the WIN_KEYBOARD_FOCUS attribute to TRUE. Note that this is only a 
hint to the window system. If the keyboard focus is tied to the pick focus, then 
this call has no effect. The target window might also refuse the keyboard focus 
request generated by this call (see KBD REQUEST under Window Events above). 
You can set the pick focus via the WlN_MOUSE_XY attribute, which sets the 
mouse cursor to a particular position within a window. 

For example, the call 



window_set (win , WIN_MOUSE_XY , 200, 300, 0); 

Vs / 



sets the cursor to the window-relative position (200, 300) and sets the pick focus 
to win. 

Input Mask An input mask specifies which events a window will receive and which events it 

will ignore. In other words, an input mask serves as a read enable mask. Each 
window has both a pick input mask, to specify which pick related events it wants, 
and a keyboard input mask, to specify which keyboard related events it wants. 

When a window is the pick focus, its pick mask is used to screen events. When a 
window is the keyboard focus, its keyboard mask is used to screen events. 



This section describes how to specify which events a window will receive and 
which it will ignore. 
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Determining which Window The Notifier determines which window will receive a given event according to 
will Receive Input the following algorithm: 

o First, the keyboard input mask for the window which is the keyboard focus 
is checked to see if it wants the event. If so, then it becomes the recipient; 
otherwise the next test is applied. 

□ Second, the pick input mask for the window which is under the cursor is 
checked to see if it wants the event. If several windows are layered under 
the cursor, then the event is tested against the pick input mask of the topmost 
window. If the mask wants the event, then it becomes the recipient; other- 
wise the next test is applied. 

o If the event does not match the pick input mask of the window under the cur- 
sor, then the event will be offered to that window’s designee. By default the 
designee is the window’s owner. You can set the designee explicitly by cal- 
ling window_set ( ) with the WIN_INPUT_DESIGNEE attribute . 33 

□ If an event is offered unsuccessfully to the root window, it is discarded. 
Windows which are not in the chain of designated recipients never have a 
chance to accept the event. 

o Occasionally you may want to specify that a given window is to receive all 
events, regardless of their location on the screen. You can do this by setting 
the WIN_GRAB_ALL_INPUT attribute for the window to TRUE. 

□ If a recipient is found, then the locator coordinates are adjusted to the coor- 
dinate system of the recipient, and the event is appended to the recipient’s 
input stream. Thus, every window sees a single ordered stream of time- 
stamped input events, which contain only the events that a window has 
declared to be of interest. 



33 Note that you must give the WIN DEVICE NUMBER of the window you wish to be the designee, not its 
handle. This is to allow specifying windows in another user process as the input designee. So the following call 
would set win2 to be the designee for winl: window_set ( winl , WIN_INPUT_DESIGNEE, 
window_get(win2, WIN_DEVICE_NUMBER) ) ; 
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6.7. Enabling and 
Disabling Events 



You specify which events a window will receive and which it will ignore by set- 
ting the window’s input masks via the following set of attributes: 



Table 6-4 



Attributes Used to Set Window Input Masks 



Events Taking a 
Single Code 

WIN_CONSUME_KBD_EVENT 
WIN_IGNORE_KBD_EVENT 
WIN_CONSUME_PICK_EVENT 
WIN IGNORE PICK EVENT 



Events Taking a Null 
Terminated List 

WIN_CONSUME_KBD_EVENTS 
WIN_IGNORE_KBD_EVENTS 
WIN_CONSUME_PICK_EVENTS 
WIN IGNORE PICK EVENTS 



The above attributes take as values either event codes such as LOC__MOVE, 
MS_LEFT, KEY_LEFT ( 2 ) , and so on, or event descriptors. The attributes in 
the left column, ending in “_EVENT”, take a single code or descriptor, while 
those on the right, ending in “_EVENTS”, take a null terminated list. 



Which Mask to Use To enable or disable ASCII events, use the keyboard mask. To enable or disable 

locator motion and button events, use the pick mask. 

Function keys are typically associated with the keyboard mask, but sometimes it 
makes sense to include some function keys in the pick mask — in effect extend- 
ing the number of buttons associated with the pick device. For example, in the 
SunView interface the [ Again ] . [ Undo 1 . f Copy 1 . ( Paste 1 . ( Cut ) . and ( Find ) func- 
tion keys are associated with the keyboard mask, while the ( Stop 1 . [Front! , and, 

I Open 1 keys are associated with the pick mask. 



Examples The event attributes cause precisely the events you specify to be enabled or dis- 

abled — the input mask is not automatically cleared to an initial state. To be 
sure that an input mask will let through the events you specify, first clear the 
mask with the special WlN_NO_EVENTS descriptor. Take, for example, the fol- 
lowing two calls: 

window_set ( win , WIN_CONSUME_PICK_EVENTS , 

WIN_MOUS E_BUTTONS , LOC_DRAG , 0 , 

0 ); 

window_set ( win , WIN_CONSUME_PICK_EVENTS , 

WIN_NO_EVENTS , WIN_MOUSE_BUTTONS , LOC_DRAG , 0, 
0 ); 



The first call adds the mouse buttons and LOCJDRAG to the existing pick input 
mask, while the second call sets the mask to let only the mouse buttons and 
LOC_DRAG through. 
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Canvases by default enable L0C_WINENTER, L0C_WINEXIT, LOC_MOVE, 
and the three mouse buttons, MS_LEFT, MS_MIDDLE, and MS_RIGHT. 34 You 

could allow the user to type in text to a canvas by calling: 


window_set( canvas, WIN_CONSUME_KBD_EVENT , WIN_ASCII_EVENTS , 0); 
s > 



Sometime later you could disable type-in by calling: 



window_set( canvas, WIN_IGNORE_KBD_EVENT , WIN_ASCII_EVENTS, 0); 

V 

An application needing to track mouse motion with the button down would 
enable LOC_DRAG by calling: 

— 
window_set( canvas, WIN_CONSUME_PICK_EVENT, LOC_DRAG , 0); 

k. 



You can enable or disable the left, right or top function keys as a group via the 
event descriptors WIN_LEFT_KEYS, WIN_RIGHT_KEYS, or 
WlN_TOP_KEYS. Note that if you want to see the up event you must also ask 
for WIN_UP_E VENTS, as in: 



window_set (win, WIN_CONSUME_KBD_EVENTS , WIN_LEFT_KEYS, 
WIN_UP_EVENTS , 0 ) ; 

L J 



In order to improve interactive performance, in the default case, windows do not 
receive locator motion events (L0C_WINENTER, L0C_WINEXIT, and 
LOC_MOVE) until after a L0C_STILL has been generated. If each window 
responds to all of the events that are generated each time the mouse passes over 
the window, then the response time of the system will be slowed down. Each 
window will “wake up” when the mouse passes over it on the way to somewhere 
else on the screen. 



If you want a window to receive all events, even if the mouse is just passing over 
the window without stopping, enable WIN_IN_TRANSIT_EVENTS, with a call 
such as: 





window_set ( canvas , WIN_CONSUME_PICK JEVENTS , 


\ 




WIN_IN_TRANSIT_EVENTS, 0 ) ; 




l 




j 



34 Note that the canvas package expects to receive these events, and will not function properly if you disable 
them. 
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Setting the Input Mask as a 
Whole 



dofeedback ( ) 

{ 

Inputmask *saved_mask; 

saved_mask = (Inputmask *) 

window_get (win, WIN_KBD_INPUT_MASK) ; 

window_set (win, WIN_KBD_INPUT_MASK , savedmask, 0); 

} 

k J 



The attributes WIN_KBD_INPUT_MASK and WIN_PICK_INPUT_MASK allow 
you to get or set an entire input mask. Let's take the example of a subroutine that 
provides interactive feedback. You can save the input mask on entry to the sub- 
routine, set up the mask as appropriate, and restore the original mask before 
returning as follows: 



Keep in mind that the inputmask pointer returned by window_get ( ) points to 
a static structure which is shared by all windows in the application. Getting 
either the keyboard or pick input masks for another window will cause the static 
structure to be overwritten. 



Querying the Input Mask You can use window_get ( ) with WlN_CONSUME_PlCK_EVENT and 

State WlN_CONSUME_KBD_EVENT to query the state of the input masks. For exam- 

ple, the following call will find out whether or not a canvas is accepting 
LOC_DRAGs: 

/ \ 

flag = ( int ) window_get ( canvas , WIN_CONSUME_PICK_EVENT , LOC DRAG); 

\ J 
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6.8. Querying and Setting You can query the state associated with an event using the following macros, all 

the Event State of which take as their only argument a pointer to an Event. 

Table 6-5 Macros to Get the Event State 



Macro 


Returns 


event action () 


The identifying code of the event. The codes are dis- 
cussed in the previous section. 35 


event is_up() 


TRUE if the event is a button or key 
event and the state is up. 


event is_down() 


TRUE if the event is a button or key 
event and the state is down. 


event x() 


The x coordinate of the locator in the window’s 
coordinate system at the time the event occurred. 


event y() 


The y coordinate of the locator in the window’s 
coordinate system at the time the event occurred. 


event shiftmask() 


The value of predefined shift-keys 
(described in kbd(5)). Possible values: 

#def ine CAPSMASK 0x0001 

#def ine SHIFTMASK OxOOOE 

#def ine CTRLMASK 0x0030 

#def ine MET A_SHI FT_MASK 0x0040 


event time( ) 


The event’s timestamp, formatted as a timeval 
struct, as defined in <sys/time .h>. 


event shift is_down() 


TRUE if one of the shift keys are down. 


event Ctrl is_down ( ) 


TRUE if the control key is down. 


event meta is_down() 


TRUE if the meta key is down. 


event is_button() 


TRUE if the event is a mouse button. 


event is ascii () 


TRUE if the event is in the ASCII range (0 thru 127). 


event_is_meta ( ) 


TRUE if the event is in the META range (128 thru 255). 


event is key left() 


TRUE if the event is any KEY LEFT ( i ) . 


event is key right () 


TRUE if the event is any KEY RIGHT ( i ) . 


event is_key top ( ) 


TRUE if the event is any KEY TOP ( i ) . 



In addition to the above macros, which tell about the state of a particular event, 
you can query the state of any button or key via the WIN_EVENT_STATE attri- 
bute. For example, to find out whether or not the first right function key is down 
you would call: 



. 

kldown = (int) 

window_get (canvas, WI N_EVENT_ST ATE , KEY_RIGHT ( 1 ) ) ; 
J 



The call will return non-zero if the key is down, and zero if the key is up. 

The following macros are provided to let you set some of the states associated 
with an event. 



35 event id ( ) is replaced by event act ion ( ) However, for compatibility, event id ( ) will still 
be supported. 
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Table 6-6 Macros to Set the Event State 



Macro 


Effect 




event set action (event , code) 
event set shiftmask 


set event’s id to code. 




(event, shiftmask) 


set event’s shiftmask to shiftmask. 
Possible values: 




#def ine CAPSMASK 


0x0001 




#def ine SHIFTMASK 


OxOOOE 




#def ine CTRLMASK 


0x0030 




#def ine META_SHI FT_MASK 


0x0040 


event_set x( event, x) 


set event’s x coordinate to x. 




event set y( event, y) 


set event’s y coordinate to y. 




event set time(event, time) 


set event’s timestamp to time. 




event set up (event) 


set state of a button event to up. 




event_set down (event) 


set state of a button event to down. 





6.9. Releasing the Event If an operation generated by an input event is going to take over 5 seconds, then 

Lock call this routine to allow other processes to get input: 36 

void 

window_release_event_lock (window) 

Window window; 



6.10. Reading Events There are times when it is appropriate to go get the next event yourself, rather 

Explicitly than waiting for it to come through the normal event stream from the Notifier. In 

particular, when tracking the mouse with an image which requires significant 
computation, it may be desirable to read events until a particular action, such as a 
mouse button up, is detected. To read the next input event for a window, bypass- 
ing the Notifier, use the function: 

int 

window_read_event (window, event) 

Window window; 

Event * event ; 

window_read_event ( ) fills in the event structure, and returns 0 if all went 
well. In case of error, it sets the global variable err no and returns -1. 

window_read_event ( ) can be used in either a blocking or non-blocking 
mode, depending on how the window has been set up 37 



36 For more details see the section on synchronization in the Workstations chapter of the SunView System 
Programmer' s Guide. 

37 window_read_event() is the high-level library standard function equivalent of input_readevent() in the 
low-level library. For further information, see Section 5.6 , Reading Input in the SunView System Programmer’ s 
Guide. 
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Note that if you read events in a canvas subwindow yourself, you must translate 
the event’s location to canvas space by calling canvas event ( ) : 

event_in_canvas_space = canvas_event( canvas , event); 
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Material Covered This chapter describes the pixwin which is the construct you use to draw or 

render images in SunView. The most basic use of pixwins is to draw in a canvas 
subwindow. 

In addition to basic pixwin usage, this chapter covers: 

□ How to boost your rendering speed by locking and batching 

□ How to use regions for clipping 

□ How to manipulate the colormap 

□ How to use the plane groups 

Related Documentation This chapter is addressed primarily to programmers who write simple applica- 

tions using canvas subwindows. For lower level details, see the chapter on 
Advanced Imaging in the SunView System Programmers Guide. 

The pixwin drawing operations do not directly support high-level graphics opera- 
tions such as shading, segments, 3-D, etc. If your application requires these, then 
you should consider some graphics package such as SunGKS, SunCore, or 
SunCGI. All of these will run in windows (see the SunCore Reference Manual 
and SunCGI Reference Manual for more information). 

Header Files The definitions necessary to use pixwins are in the header file 

<sunwindow/pixwin . h>, which is included by 

<s unwin dow/window_hs . h>, which in turn is included by default when 
you include <suntool/sunview.h>. 

Summary Listing and Tables To give you a feeling for what you can do with pixwins, the following page con- 

tains a list of the available pixin functions and macros. Many of these are dis- 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the pixwin summary tables in Chapter 
19, SunView Interface Summary : 

□ the Pixwin Drawing Functions and Macros , 

□ the Pixwin Color Manipulation Functions. 
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Pixwin Drawing Functions and Macros 



batch (pw, n) 

_batch_of f (pw) 

_ba tch_on ( pw ) 

batchrop ( pw , dx , dy , op , items , n ) 

_char(pw, x, y, op, font, c) 
close(pw) 

_copy(dpw, dx, dy, dw, dh, op, spw, sx, sy) 
get(pw, x, y) 
getreg ion_r ect ( pw , r ) 

_line(pw, xO, yO, xl, yl, brush, tex, op) 

_lock(pw, r) 

_pfsysclose( ) 

_pf sysopen ( ) 

_polygon_2 ( pw, dx, dy, nbds, npts , vlist, op, spr, sx, sy) 
_polyline(pw, dx, dy, npts, ptlist, mvlist, brush, tex, op) 
polypoint (pw, dx, dy, npts, ptlist, op) 

_put(pw, x, y, value) 

_read(pr, dx, dy, dw, dh, op, pw, sx, sy) 
region (pw, x, y, width, height) 

_replrop(pw, dx, dy, dw, dh, op, pr, sx, sy) 
reset (pw) 

_rop(pw, dx, dy, dw, dh, op, sp, sx, sy) 

_set_region_rect (pw, r, use_same_pr) 
show(pw) 

_stencil(dpw, dx, dy, dw, dh, op, stpr, stx, sty, spr, sx, sy) 
_text(pw, x, y, op, font, s) 

_traprop(pw, dx, dy, t, op, pr, sx, sy) 

_ttext(pw, x, y, op, font, s) 
unlock ( pw) 

vector (pw, xO, yO , xl, yl, op, value) 

_write(pw, dx, dy, dw, dh, op, pr, sx, sy) 

_writebackground(pw, dx, dy, dw, dh, op) 



Pixwin Color Manipulation Functions 



pw_blackonwhite(pw, min, max) 
pw_cyclecolormap(pw, cycles, index, count) 
pwdblacces s ( pw ) 
pw_dbl_f 1 ip ( pw ) 
pw_dbl_get(pw, attribute) 
pw_dbl_release( ) 
pw_dbl_set(pw, attributes) 
pw_getattributes ( pw, planes ) 
pw getcmsname ( pw , cmsname ) 



pw_getcolormap ( pw , index , count , 
red, green, blue) 
pw_getdefaul terns ( ems , map) 
pw_putattr ibutes ( pw , planes ) 
pw_putcolormap ( pw , index , count , 
red, green, blue) 
pw_reversevideo ( pw , min , max ) 
pw_s etems name ( pw , ems name ) 
pw whiteonblack (pw, min, max) 
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7.1. What is a Pixwin? An image in SunView, whether on the screen or in memory, is composed of dots 

called pixels and is represented internally as a rectangle of such pixels. The pix- 
rect structure is the construct used at a low level to access an image and operate 
on it. You can program at the pixrect level to draw on the screen; this is covered 
in the Pixrect Reference Manual . 

However, in SunView drawing operations are displayed in a window coexisting 
on the screen with other, possibly overlapping windows. Except in certain cir- 
cumstances, drawing operations should be “well-behaved,” meaning that they 
should not spill over into other windows and they should not be visible in por- 
tions of the window which are covered by other windows. The pixwin is the 
interface through which you operate on the pixels in a particular window. It 
guarantees that the above two conditions will be met. 

Each pixel has a value. On a monochrome display the value is 1 or 0, since the 
pixel can only be on or off, black or white. Such pixels are said to be 1 bit deep. 
On a color display each pixel can have several values corresponding to different 
colors. 

This section summarizes the functions provided for accessing the pixels of a 
pixwin. Most of the pw_* functions described in this section are based on 
corresponding pr_* routines, which are fully documented in the Pixrect Refer- 
ence Manual. For full discussion of the semantics of a given pixwin function, 
refer to the discussion of the corresponding pixrect function in the Pixrect Refer- 
ence Manual and/or the errata/addenda section of the most recent Release 
Manual. 

In particular the pixrect manual gives useful values for the op argument which 
determines what the result of combining the source and destination pixels will 
be. 

The procedures described in this section will maintain the memory pixrect for a 
retained pixwin. That is, they perform their operation on the data in memory, as 
well as on the screen. 

Obtaining the Window’s All of these procedures require the pixwin of the window you are drawing in as 

Pixwin an argument. To draw in a canvas, you use the pixwin that is returned by the 

procedure: 

Pixwin * 

canvas_pixwin ( canvas ) ; 

Canvas canvas; 

Look at the example in Section 5.1, Creating and Drawing into a Canvas, to see 
how canvas_pixwin ( ) is used. 

The pixwin is also available as the value of the CANVAS_PIXWIN attribute of 
the canvas subwindow. 38 



38 Aside from the canvas pixwin, all windows, regardless of type, have a pixwin which is available as the 
value of WIN PIXWIN. However, most applications should not need to explicitly write pixels into other types 
of windows. 



7.2. Accessing a Pixwin’s 
Pixels 
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Write Routines 



Basic RasterOp Operations 



Other Raster Operations 



The following routines allow you to draw areas, backgrounds, vectors, text, 
polygons, lines, and polylines in a pixwin. 

The following are the basic low-level raster operations that draw on the screen. 
They are common to many imaging systems. 

pw_write(pw, dx, dy, dw, dh, op, pr, sx, sy) 

— or — 

pw_rop(pw, dx, dy, dw, dh, op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 



pw_write ( ) and pw_rop ( ) are different names for the same procedure. 

They perform the indicated rasterop (op) from the source pixrect to the destina- 
tion in the pixwin. Pixels are written to the rectangle defined by dx, dy, dw, and 
dh in the pixwin pw using rasterop function op. dx and dy are the position of 
the top left-hand comer of the rectangle, and dw and dh are the width and height 
of the rectangle. They are copied from the rectangle with its origin at sx, sy in 
the source pixrect pointed to by pr. 

pw_write ( ) is essential for many window system operations such as scrolling 
a window, drawing frames and borders, and drawing an icon on the screen. 

The routines in this section are variations on the basic rasterop routine. 

pw_writebackground(pw, dx, dy, dw, dh, op) 

Pixwin *pw; 

int dx, dy, dw, dh, op; 



pw writebackground ( ) uses a conceptually infinite set of pixels, all of 
which are set to zero, as the source. It is often used to clear a canvas pixwin 
before drawing a new image . 39 

The following routine draws a pixel of value at ( x, y ) in the addressed 
pixwin: 

pw_put(pw, x, y, value) 

Pixwin *pw; 

int x, y, value; 

Using this routine to draw is very slow and should be avoided. If you use it, be 
sure to read the later sections on batching and locking. 



39 Canvases will automatically clear damaged areas if they are set not to be retained, or if the attribute 
CANVAS_AUTO_CLEAR is set. See Chapter 5, Canvases, for more information. 
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Text Routines 



There is a similar routine to draw many pixels in a single call. 

pw_polypoint(pw, dx, dy, npts, ptlist, op) 

Pixwin *pw; 

int dx, dy, npts; 

struct pr_pos *ptlist; 
int op; 

All npts points in the array ptlist are drawn in the pixwin pw starting at the 
offset dx, dy under the control of the op argument. 

The next routine draws a vector of pixel value from (xO, yO) to (xl, yl) in the 
addressed pixwin using rasterop op: 

pw_vector (pw, xO, yO, xl, yl, op, value) 

Pixwin *pw; 

int xO, yO, xl, yl, op, value; 

To replicate a pattern in a pixrect onto a pixwin, use: 

pw_replrop(pw, dx, dy, dw, dh, op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 



pw_replrop ( ) replicates a small “patch” of pattern in a pixrect onto an entire 
pixwin. It is often used to draw a patterned background in a window, such as the 
root gray pattern in sunview(l). Standard patterns, created by iconedit(l), 
may be found in /usr/include/images/square__* . pr. 



The following two routines write a string of characters and a single character, 
respectively, to a pixwin, using rasterop op as above: 



text ( pw , 


x, y, op, font, 


s) 


Pixwin 


*pw; 




int 


x, y, op; 




Pixfont 


*font; 




char 


*s; 




char (pw. 


x, y, op, font, 


c) 


Pixwin 


*pw; 




int 


x, y, op; 




Pixfont 


* font ; 




char 


c; 
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Batching and Stenciling 
Routines 



These text rendering routines are distinguished by their own coordinate system: 
the destination is given as the left edge and baseline of the first character. The 
left edge does not take into account any kerning (character position adjustment 
depending on its neighbors), so it is possible for a character to have some pixels 
to the left of the x-coordinate. The baseline is the y-coordinate of the lowest 
pixel of characters without descenders, ‘L’ or ‘o’ for example, so pixels will fre- 
quently occur both above and below the baseline in a string . 40 

font may be NULL in which case the system font is used. 

The system font is reference counted and shared between software packages. 
The following routines are provided to open and close the system font : 41 

Pixfont * 
pw_pf sysopen( ) 

pw_pf sysclose( ) 



The following routine: 



ttext ( pw , 


x, y, 


op, font 


Pixwin 


*pw; 




int 


x, y, 


op; 


Pixfont 


*font; 




char 


*s; 





s) 



is just like pw_text ( ) except that it writes transparent text. Transparent text 
writes the shape of the letters without disturbing the background behind it. This 
is most useful with color pixwins. Monochrome pixwins can use pw text ( ) 
and a PIX_SRC | PIX_DST op, which is faster. 



Applications such as displaying text perform the same operation on a number of 
pixrects in a fashion that is amenable to global optimization. The batchrop pro- 
cedure is provided for these situations: 



pw_ba t chr op ( pw , dx , 
Pixwin 
int 

struct pr_prpos 



dy, op, items, n) 
*pw; 

dx, dy, op, n; 
items [ ] ; 42 



Stencil operations are like raster ops except that the source pixrect is written 
through a stencil pixrect which functions as a pixel-by-pixel write enable mask. 
The indicated raster operation is applied only to destination pixels where the 
stencil pixrect stpr is non-zero; other destination pixels remain unchanged. 



40 A font to be used in pw_t ext ( ) is required to have the same pc home . y and character height for all 
characters in the font. 

41 The system font can also be obtained by calling pf def ault ( ) . 

42 The structure of pr_prpos is given in Appendix C of the Pixrect Reference Manual. 
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pw_stencil(dpw / dx, dy, dw, dh, op, stpr, stx, 
sty, spr, sx, sy) 

Pixwin * dpw ; 

Pixrect *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 



Drawing Polygons 



Drawing Curved Shapes 



Drawing Lines 



The following function draws a polygon within a pixwin: 

pw_polygon_2(pw, dx, dy, nbds, npts, vlist, op, spr, sx, sy) 
Pixwin *pw; 

int dx, dy, nbds, op, sx, sy; 

int npts [ ] ; 

struct pr_pos * vlist; 

Pixrect *spr; 

You can create a polygon filled with a solid or textured pattern. 

pw__traprop ( ) is a pixwin operation analogous to pw_rop ( ) , which 
operates on a trapezon rather than a rectangle: 



traprop(pw, 


dx, 


dy, t, op, pr, sx, sy) 


Pixwin 




*pw; 


struct pr 


trap 


t; 


Pixrect 




*pr ; 


int 




dx, dy, op, sx, sy; 



pw_traprop ( ) writes the source pixrect pr into the destination pixwin pw via 
the operation op. The output is clipped to the trapezon t. 



The following routine draws a solid or textured line between two points with a 
“brush” of a specified width: 

pw_line(pw, xO, yO, xl, yl, brush, tex, op) 

Pixwin *pw; 

int xO, yO, xl, yl, op; 

struct pr_brush *brush; 
struct pr_texture *tex; 



There is a similar routine to draw several noncontiguous line segments between a 
set of points: 



pw polyline(pw, dx, dy, npts, ptlist, mvlist, 



Pixwin 

int 

struct pr_pos 
u_char 

struct pr_brush 
struct pr_texture 



*pw; 

dx, dy, npts, op; 
*ptlist; 

*mvlist; 

*brush 

*tex; 



brush, 



tex, 



op) 
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Read and Copy Routines 



7.3. Rendering Speed 



The following routines use the pixwin as a source of pixels. To get the value of 
the pixel at ( x, y ) in pixwin pw call: 

int 

pw_get(pw, x , y) 

Pixwin *pw; 
int x, y; 

To read pixels from a pixwin into a pixrect call: 

pw_read(pr, dx, dy, dw, dh, op, pw, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 

This routine reads pixels from pw starting at offset ( sx, sy ), using rasterop op. 
The pixels are stored in the rectangle with its origin at dx, dy of width dw and 
height dh in the pixrect pointed to by pr. 

When the destination, as well as the source, is a pixwin, use: 

pw_copy(dpw, dx, dy, dw, dh, op, spw, sx, sy) 

Pixwin *dpw, *spw; 

int dx, dy, dw, dh, op, sx, sy; 

dpw and spw must be the same pixwin. Also, only horizontal or vertical copies 
are supported. 

These read and copy routines fail if they try to read from a portion of a non- 
retained pixwin which is hidden, and therefore has no pixels. Therefore it is con- 
sidered advanced usage to call them on a non-retained pixwin; refer to the section 
entitled Handling Fixup in the SunView System Programmer’s Guide. 

Making correct and judicious use of explicit display locking and/or batching is 
important for getting the best display speed possible. 

There are two major impediments to you getting the best possible display render- 
ing speed. The first is display locking , which prevents window processes from 
interfering with each other in several ways: 

□ Raster hardware may require several operations to complete a change to the 
display; one process’ use of the hardware should be protected from interfer- 
ence by others during this critical interval. 

a Changes to the arrangement of windows must be prevented while a process 
is painting, lest an area be removed from a window as it is being painted. 

□ A software cursor that the window process does not control (the kernel is 
usually responsible for the cursor) may have to be removed so that it does 
not interfere with the window’s image. 

Display locking is relatively expensive compared to the time it takes to do simple 
display operations. Thus you can reduce your display time by reducing the 
number of times that you have to acquire the display lock. The subsection below 
titled Locking explains how to do this. 



m 
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Locking 



The second major impediment to maximum display speed is the use of retained 
pixwins. It is obvious that if you have to write to the screen and to memory for 
every display operation that it will take longer than writing to only one place. 
Thus, there is a mechanism, called pixwin batching which allows you to write 
only to memory and then refresh the screen with a quick raster operation from 
memory. The subsection entitled Batching explains how to use batching. 

Locking allows a client program to obtain exclusive use of the display. If the 
client program does not obtain an explicit lock, the window system will. For 
example, if your application is going to draw one hundred lines it can either 
explicitly lock the display once, draw the lines, and unlock explicitly, or it can 
ignore locking and simply draw the lines. In the latter case, the window system 
will perform locking and unlocking around each drawing operation, acquiring 
and releasing the lock one hundred times instead of once. 

NOTE For efficiency’s sake, application programs should lock explicitly around a body 
of screen access operations. 

You can acquire a lock by calling the macro: 

pw_lock ( pw , r ) 

Pixwin *pw; 

Rect *r; 

pw is the pixwin to be used for the output; r is the rectangle in the pixwin’ s coor- 
dinate system that bounds the area to be affected. See The Rect Structure in 
Chapter 4, Using Windows , for an explanation of the Rect structure, 
pw lock ( ) blocks if the lock is unavailable (if, for example, another process 
currently has the display locked). 

When the cursor is on the surface where drawing occurs, if the pixwin is locked 
with pw lock ( ) , sometimes the region in which the cursor rect resides is not 
drawn to. This results in an empty region (16 x 16 pixels) when the cursor is 
moved. The image is put to its correct state when it is redisplayed. 

Lock operations for a single pixwin may be nested; inner lock operations merely 
increment a count of locks outstanding and are thus very lightweight. Their 
affected rectangles must lie within the rectangles affected by the original lock. 

To decrement the lock count, call: 

pw_unlock ( pw ) 

Pixwin *pw; 

When the lock count reaches 0, the lock is actually released. 

Since locks may be nested, it is possible for a client procedure to find itself, espe- 
cially in error handling, with a lock which may require an indefinite number of 
unlocks. To handle this situation cleanly, another routine is provided. The fol- 
lowing macro sets pw’s lock count to 0 and releases its lock: 

pw_r e s e t ( pw ) 

Pixwin *pw; 
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Batching 



Acquisition of a lock has the following effects: 

□ If the cursor is in conflict with the affected rectangle, it is removed from the 
screen. While the screen is locked, the cursor will not be moved in such a 
way as to disrupt any screen accessing. 

□ Access to the display is restricted to the process acquiring the lock. 

□ Modification of the database that describes the positions of all the windows 
on the screen is prevented. 

□ The clipping information for the pixwin is validated and, if necessary, 
updated. 

□ In the case of a non-retained pixwin with only a single rectangle visible, the 
internals of the pixwin mechanism can be set up to bypass the pixwin 
software by going directly to the pixrect level on subsequent display opera- 
tions. 

While it has the screen locked, a process should not: 

□ do any significant computation unrelated to displaying its image. 

□ invoke any system calls, including other I/O, which might cause it to block. 

□ invoke any pixwin calls except pw_unlock ( ) and those described in the 
previous section, Accessing a Pixwin’ s Pixels. In any case, the lock should 
not be held longer than about a quarter of a second, even following all these 
guidelines. 

When a display lock is held for more than two seconds of process virtual time, 
the lock is broken. However, the offending process is not notified by signal, 
because a process shouldn’t be aborted for this infraction. Instead, a message is 
displayed on the console. 

Batching allows you to write only to the memory pixrect of a retained pixwin and 
then refresh the screen with the memory pixrect’ s contents at specific times. If 
you do not explicitly batch when using a retained pixwin, the window system 
will write to both the display and memory on every display operation. 

Considering the same example used for locking above, if your application pro- 
gram has a retained pixwin and is going to draw one hundred lines, it can either 
explicitly start a batch, draw the lines, and end the batch explicitly, or it can 
ignore batching and simply draw the lines. In the latter case, the window system 
will draw the lines two hundred times instead of one hundred times. 

NOTE For efficiency’s sake, application programs should batch explicitly around a 
body of screen access operations when using a retained pixwin. 
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Two macros are provided to control batching: 

pw_batch__on ( pw ) 

Pixwin *pw; 

pw_batch_of f ( pw) 

Pixwin *pw; 



pw_batch_on( ) starts a batch; pw_batch_of f ( ) refreshes the screen with 
the portion of the memory pixrect that has changed. While batching, the pixwin 
internally maintains a rectangle that describes which pixels in the memory pix- 
rect need to be transferred to the screen at the end of the batch. 

NOTE Don’t turn batching on and leave it on, as this causes problems with scrolling. 
The recommended use is batch_on ( ) (draw something in window ) 
batch_of f ( ) . 

While in the middle of batching, your code might reach a point at which you 
would like the screen to be updated. The following macro refreshes the screen, 
but otherwise doesn’t change the batching mode: 

pw_show( pw) 

Pixwin *pw; 

Unlike locking operations, batch operations for a single pixwin do not nest. 

Thus, each batching routine in this section affects the batching mode/status. 

These three macros — pw_batch_on ( ) , pw_batch_of f ( ) and 
pw_show( ) — all call the routine pw_batch( ) which actually implements 
the batching mechanism. You can call pw_batch( ) directly to tell the batch- 
ing mechanism to refresh the screen after every n display operations. 

pw_batch(pw, kind) 

Pixwin *pw; 

Pw_batch_type kind; 

Because the routine does more than one kind of thing, calling it is a little tricky, 
kind is the kind of batching requested. You use the following macro to convert 
n,the number of display operations you want to be batched before a refresh, to a 
Pw_batch_type: 

#define PW_OP_COUNT ( n ) ( ( Pw_batch_type) ( n) ) 

So, to have batching and ensure the image on-screen is refreshed after every n 
operations, call: 

pw_ba tch ( pw , PW_OP_COUNT ( n ) ) ; 

Clients with a group of screen updates to do can gain noticeably by doing the 
group as a batch. Also, the locking overhead, discussed above, will only be 
incurred when the screen is refreshed. An example of such a group is displaying 
a screen full of text, or a series of vectors with pre-computed endpoints. 

In considering how to do batching, it’s a good idea to be sensitive to how long 
the user is staring at a blank screen or an old image, and adjust the rate of screen 
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refresh accordingly. 

Locking and Batching There are situations in which batching around locking calls makes sense. Con- 

Interaction sider that 

□ while batching, locking calls are a no-op; 

□ if a pixwin is not retained, batching calls are a no-op. 

Thus, if your application has a switch to run retained or not, it makes good sense 
to batch around locking calls. If you batch around locking calls then your appli- 
cation gets the benefit of batching if running retained and the benefit of locking if 
running non-retained. 

Locking around batches, on the other hand, is not very efficient. 

7.4. Clipping With Regions You can use pixwins to clip rectangular regions within a window's own rec- 
tangular area. The region operation creates a new pixwin that refers to an area 
within an existing pixwin: 

Pixwin * 

pw_region(pw, x, y, w, h) 

Pixwin *pw; 

int x, y , w, h; 

pw is the source pixwin; x, y, w and h describe the rectangle to be included in 
the new pixwin. The upper left pixel in the returned pixwin is at coordinates 
(0,0); this pixel has coordinates ( x, y) in the source pixwin. 

If the source pixwin is retained, the new region will be retained as well. How- 
ever, the region refers back to the bits of memory pixrect of the source pixwin 
when accessing the image. 

To change the size of an existing region, call: 

int 

pw_set_region_rect(pw, r, use_same_pr) 

Pixwin *pw; 

Rect *r; 

unsigned use_same_pr; 

The position and size of the region pw are set to the rect *r; a return value of - 1 
indicates failure. This is more efficient then destroying the old region and creat- 
ing a new one. The use same pr flag should be set to 0 if you want a new 
retained pixrect allocated for the region that is the size of the region. 

To determine the size of an existing region, call: 

int 

pw_get_region_rect(pw, r) 

Pixwin *pw; 

Rect *r; 
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7.5. Color 



Introduction to Color 



The Colormap 



*r is set to the size and position of the region pw. 

When finished with a region, you should release it by calling: to: 

pw_close(pw) 

Pixwin *pw; 

This routine frees any dynamic storage associated with the pixwin, including its 
retained memory pixrect, if any. If the pixwin has a lock on the screen, it is 
released. 

NOTE You should close any regions before closing the pixwin containing the regions. 

The dicussion which follows is divided into three sections: 

□ Introduction to Color , which introduces the concepts of the colormap and 
colormap segments, 

□ Changing the Colormap, which describes how to change a colormap seg- 
ment, and 

□ Using Color, which describes how to make color applications compatible 
with monochrome and grayscale screens, and how to perform smooth anima- 
tion by using double buffering. 

Just as there must be arbitration between different windows to decide what is 
displayed on the screen when several windows overlap, there must likewise be 
some process of allocation when several windows want to display different sets 
of many colors all at once. To understand how this works you need to know how 
color is handled. 

The pixels on a color display are not simply on or off; they take many different 
values for different colors. On all current Sun color displays 43 each pixel has 8 
bits. Such an “8 bit deep” pixel can have any value from 0 to 255. The value in 
each pixel helps to determine what color appears in that dot on the screen, but it 
is not in a one-to-one correspondence with the color displayed; otherwise Sun 
color displays would only be able to display 256 different colors. 

Instead, the value of the pixel serves as an index into the colormap of the display. 
The colormap is an array of 256 colormap entries. The colormap entry for each 
index drives the color that is actually displayed for the corresponding pixel value. 
A colormap entry consist? of 8 bits of red intensity, 8 bits of green intensity and 
8 bits of blue, packaged into the following structure: 

struct singlecolor { 

u_char red, green, blue; 

} ; 

Hence a Sun color display is capable of displaying over 16 million colors 
(because each colormap entry has 24 bits) but can only display 256 colors simul- 
taneously (because there are only 256 colormap entries). 



43 See cgone(4S), cgtwo(4S) and cgf our(4S) in the UNIX Interface Overview manual. 
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A Colormap Example 



Changing the Colormap 



Colormap Segments 



Suppose that in a group of pixels on the screen, some have the value 0 while oth- 
ers have the value 193. All pixels with the same value will be displayed in the 
same color. The colormap determines what that color will be. If entry 0 in the 
colormap of the screen is 

red = 250; green = 0; blue = 3; 

then the pixels with a value of 0 will come out bright red. If entry 0 in the color- 
map is changed to 

red = 1; green = 8; blue = 2; 

then the pixels with a value of 0 will immediately change color to an almost- 
black green. Similarly, entry 193 in the colormap determines what color the pix- 
els with a value of 193 will have. 

Because changing the colormap is much faster than redrawing many thousands of 
pixels with a new value, manipulating the colormap is the basis of many graphics 
and animation techniques. For examples of programs that manipulate the color- 
map, run /usr/demo/suncube or /usr/demo/f light. 

Try running spheresdemo -g plus another color program at the same time. 
You will notice that as you move the mouse into the spheresdemo window, 
the colors in the other windows on the display change dramatically. This is 
because hardware is only capable of displaying 256 colors at once. When two 
programs that each want to display 256 different colors are run simultaneously, 
the window system itself must manipulate the colormap. When the cursor enters 
one of the windows, the window system changes the colormap to use the colors 
of that window. 

The window system allows each window to claim a portion of the total available 
colormap entries, called a colormap segment. The colormap segment occupies 2, 
4, 8, 16, 32, 64, 128 or 256 bytes Frames and subwindows can have different 
colormaps, or can share colormaps (see Sharing Colormap Segments below). 

If the total number of entries in all the colormap segments being requested 
exceeds the limit of 256 at any given time, the window system gives priority to 
the window under the cursor, and removes segments belonging to other windows 
as necessary. 

Note that this swapping of colormap segments can cause visible flashing on the 
screen as the cursor moves between windows. 

The window system stores colormap segments at arbitrary locations within the 
colormap, transparently to the application program. The routines that access a 
pixwin’s pixels do not distinguish between windows which use colormap seg- 
ments and those which use the entire colormap. 

NOTE While you can have multiple pixwins within a window, there is only one color- 
map segment per window. A separate colormap for each pixwin in a window is 
not supported. This limitation should only be of interest if you are using pixwin 
regions ( described in the SunView System Programmer’s Guide). 
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Background and Foreground 



Default Colormap Segment 



Changing Colors from the 
Command Line 



Sharing Colormap Segments 



Every colormap segment has two distinguished values, its background and fore- 
ground, which are the values stored in first and last positions of the colormap 
segment, respectively. A monochrome colormap segment has just 2 values, its 
background at location 0 and its foreground at location 1. 

The first pixwin created for a window sets the background and foreground of the 
window to be those of the default colormap segment. This is the monochrome 
colormap segment defined in <sunwindow/cms_mono . h> . Subsequent 
pixwins created for the window inherit the background and foreground of the 
window. 

The user can modify the default colormap for all applications by invoking - 
sunview with the -F and -B command line arguments. 44 The user can also 
change the default colormap segment on a per-application basis by invoking the 
application with certain flags. The -Wf flag sets the foreground color, -Wb sets 
the background color, and -Wg specifies that the colormap of the frame will be 
inherited by the frame’s subwindows. 

The equivalent frame attributes for these flags are 
FRAME_FOREGROUND_COLOR, FRAME_BACKGROUND_COLOR, and 
FRAME_INHERIT_COLORS. 

If you set the FRAME_lNHERiT_COLORS attribute to TRUE for subwindows 
before setting up a colormap for the frame, the sub windows will not inherit the 
colors of the frame. The correct procedure is to set the attribute after the color- 
map. 



r 

THIS WAY 

my_set_colormap_f unction ( ) ; 




\ 


window_set ( frame , FRAME_INHERIT_COLORS , TRUE , 


0); 




NOT THIS WAY 


window_set( frame, FRAME_INHERIT_COLORS , TRUE, 
my_set_colorma p_f unction ( ) ; 


0); 




V 




> 



It is possible for different processes to share a single colormap segment. For 
some applications, you want to guarantee that your colormap segment is not 
shared by another process. For example, a colormap segment to be used for ani- 
mation, as described later in the section on Double Buffering, should not be 
shared. The way to ensure that a colormap segment will not be shared by another 
window is to give it a unique name. A common way to generate a unique name 
is to append the process’ id to a more meaningful string that describes the usage 
of the colormap segment. 



44 This is not true for a Sun-3/1 10 and other machines with eg four frame buffers, due to their use of an 
overlay plane to implement most monochrome windows. 
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Example: showcolor 



If a colormap segment’s usage is static in nature, then it pays to use a shared 
colormap segment definition, since colormap entries are scarce. Windows, in the 
same or different processes, can share the same colormap by referring to it by the 
same name. 

There are three basic types of shared colormap segments: 

□ A colormap segment used by a single program. Sharing occurs when multi- 
ple instances of the same program are running. An example of such a pro- 
gram is a color terminal emulator in which the terminal has a fixed selection 
of colors. 

□ A colormap segment used by a group of highly interrelated programs. Shar- 
ing occurs whenever two or more programs of this group are running at the 
same time. An example of such a group is a series of CAD/CAM programs 
in which it is common to have multiple programs running at the same time. 

o A colormap segment used by a group of unrelated programs. Sharing occurs 

whenever two or more programs of this group are running. An example of 
such a colormap segment is the default colormap, CMS_MONOCHROME, 
defined in <sunwindow/cms_mono . h> . Other common useful color- 
map segment definitions that you can use and share with other windows 
include cms_rgb . h, cms_grays . h, cms_mono . h, and 
cms_rainbow . h, found in <sunwindow/cms_* . h> . 

The program on the following page shows the actual colors in the display’s 
colormap. It should help you see how the window system manages the color- 
map. Run this program soon after bringing up sun view, then run several color 
graphics programs such as the demos mentioned earlier. Try bringing up dif- 
ferent windows with different foreground and background colors, as in: 







a 




% shelltool -Wf 23 182 48 -Wb 255 200 230 -Wg 








j 



y*************************************************************/ 

/* V 

/* showcolor.c */ 

/* V 

y*************************************************************y 

y*************************************************************y 

/* V 

/* This application displays the colormap on the canvas when */ 

/* the user has not placed the cursor in the canvas of this */ 
/* tool. The user has the ability to close, move, resize, */ 

/* hide, redisplay, or quit the window. */ 

/* V 

y*************************************************************^/ 



/* 



* showcolor.c 

* Draw a grey ramp that graphically shows the colormap 

* segment activity of the environment when the cursor 

* is NOT in the canvas of this tool. 
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*/ 



#include <suntool/sunview. h> 
#include <suntool/canvas . h> 
#def ine CMS_SIZE 256 

#def ine CAN_HEIGHT 10 

main(argc, argv) 

char **argv; 

{ 



Frame 

Canvas 

register Pixwin 
register int 
u char 



frame; 
canvas ; 

*pw; 
i ; 

red [CMS_SIZE] , 
green [CMS_SIZE] , 



blue [CMSSIZE] ; 

/* Create frame and canvas */ 
frame = window_create ( 0 , FRAME, 

FRAME_LABEL , argv [ 0 ] , 
FRAME_ARGS, argc, argv, 



0 ); 



canvas = window_create ( frame, CANVAS, 

V?IN_HEIGHT, CAN_HEIGHT, 
WIN_WIDTH, 2 * CMS_SIZE, 
0 ); 



window_f it (frame) ; 

pw = canvas_pixwin ( canvas ) ; 

/* Initialize colormap to grey ramp */ 
for (i = 0; i < CMS_SIZE; i++) 

red[i] = green [i] = blue[i] = i; 
pw_setcmsname ( pw, " showcolor " ) ; 

pw_putcol o rm a p (pw, 0, CMS_SIZE, red, green, blue); 

/* Draw ramp of colors */ 

for (i = 0; i < CMS_SIZE; i++) 

pw_rop (pw, i*2, 0, 2, CAN_HEIGHT , 

PIX_SRC | PIX_C0L0R ( i ) , (Pixrect *)0, 0, 
window_main_loop ( frame) ; 
exit ( 0 ) ; 



1 



0 ); 



Manipulating the Colormap The following sections document the routines that implement the techniques 

described above. 



To change a window’s colormap segment, you must: 

1. Name the colormap segment with pw_setcmsname ( ) . 

2. Set the size of the segment by loading the colors with 
pw_putcolormap ( ) . 

It is important that these two steps happen in order and together. The call to 
pw_setcmsname ( ) does not take effect until you write at least one color 
value into the colormap with pw_putcolormap ( ) . 
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You set and retrieve the name of a colormap segment with these two functions: 

pw_se terns name ( pw , name ) 

Pixwin *pw; 

char name [CMS_NAMESIZE] ; 

pw_ge tems name ( pw , name ) 

Pixwin *pw; 

char name [CMS_NAMESIZE ] ; 



If you set the foreground and back- 
ground colors (which are entries 
count - 1 and 0 in the colormap 
segment, respectively) to the same 
color, the system will change them 
to the foreground and background 
colors of sunview. In other words, 
you are prevented from making the 
foreground and background colors 
of a pixwin indistinguishable. 



Setting the name resets the colormap segment to a NULL entry. After calling 
pw_setcmsname ( ) , you must immediately call pw_put colormap ( ) to set 
the size of the colormap segment and load it with the actual colors desired. 
pw_putcolormap ( ) and the corresponding routine to retrieve the colormap’s 
state, pw_getcolormap( ) , are defined as follows: 

pw_putcolormap(pw, index, count, red, green, blue) 

Pixwin *pw; 

int index, count; 

unsigned char red[], green[], blue [ ] ; 



pw_getcolormap(pw, index, count, red, green, blue) 
Pixwin *pw; 

int index, count; 

unsigned char red[ ], green [ ], blue[ ]; 



pw_putcolormap loads the count elements of the pixwin’s colormap seg- 
ment starting at index (zero origin) with the first count values in the three 
arrays. 

The first time pw_putcolormap ( ) is called after calling 
pw_setcmsname ( ) , the count parameter defines the size of the colormap 
segment. The size of a colormap segment must be a power of 2, and can’t be 
changed unless pw_setcmsname ( ) is called with another name. You can call 
pw_putcolormap ( ) subsequently to modify a subrange of the colormap — 
use a larger value for index and a smaller value for count. 

NOTE If you attempt to install a colormap segment that is not a power of 2, your color- 

map segment has a high likelihood of taking up too much space. This means that 
the screen will flash when you move the cursor into the window with this odd 
sized colormap. 

In Appendix A, Example Programs, there is a program called color edit which 
uses pw_putcolormap( ) to change the colors of its subwindows as the user 
adjusts sliders for red, green and blue. 



Cycling the Colormap A utility is provided to make it easy to cycle colormap entries: 

pw_cyclecolormap(pw, cycles, index, count) 
Pixwin *pw; 

int cycles, index, count; 
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Miscellaneous Utilities 



Using Color 



Cursors and Menus 



Starting at index, the count entries of the colormap associated with the 
pixwin’s window are rotated among themselves for cycles. A cycle is defined 
as number of shifts it takes one entry to move through every position once. 

To see an example of colormap cycling, run j umpdemo (6) with the - c option. 

If you are are going to cycle one of the common colormap segment definitions, 
you should give the colormap a unique name, otherwise the colormap of other 
applications will change as well. 



The following utilities are provided as convenient ways to set the forground and 
background colors to common settings, min should be the first entry in the 
colormap segment, representing the background color, max should be the last 
entry, representing the forground color. 

pw_reversevideo(pw, min, max) 

Pixwin *pw; 
int min, max; 



pw_blackonwhite(pw, min, max) 
Pixwin *pw; 
int min, max; 



pw_whiteonblack(pw, min, max) 
Pixwin *pw; 
int min, max; 



On a monochrome display, these calls don’t take effect until you write to the 
pixwin. On a color display, they take effect immediately. 

This section gives some notes on the use of color by cursors and menus, how to 
make color applications compatible with monochrome and grayscale screens, and 
how to use double buffering for smooth animation. 

Cursors appear in the foreground color, the last color in the pixwin’s colormap. 

Menus and prompts use fullscreen access , covered in Chapter 12, Menus and 
Prompts , of the SunView System Programmer' s Guide. Fullscreen access saves 
the colors in the first and last entries of the screen's colormap, puts in the fore- 
ground and background colors, and displays the menu or prompt. This means 
that depending on where your application's colormap segment resides in the 
screen’s colormap, some colors in your tool may change whenever menus or 
prompts are put up. You can allow for this by making the background and fore- 
ground colors in your colormap segment the same as the screen’s background 
and foreground. 

There are other menu/cursor “glitches" that occur when running applications on 
frame buffers which support multiple plane groups. These are covered in the 
later section on Multiple Plane Groups. 
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Is My Application Running on a None of the colormap manipulations described in this chapter causes an error if 

Color Display? run on a monochrome display. All colors other than zero map to the foreground 

color, so if your application displays colored objects on a background of zero, 
they will appear as black objects on a white foreground on a monochrome 
display 45 . The window system detects and prevents the foreground and back- 
ground being the same color on color displays. 

However, you may may want to determine at run time whether your application 
has a color or monochrome display available to it. For example, when displaying 
a chart, you may want to use patterns if colors are not available. You can deter- 
mine whether the display is color or monochrome by finding out how deep the 
pixels are. Each pixwin includes a pointer to a pixrect which represents its pixels 
on the screen. Pixrects, in turn, have a depth field which holds the number of bits 
per screen pixel. Thus 





Pixwin *pw; 






int depth = pw->pw_pixrect->pr_depth; 


j 



will have a value of 1 for windows displayed on monochrome devices, and a 
value greater than 1 for color screens. Currently, all Sun color displays have 8 
bits per pixel. 

Simulating Grayscale on a There is no way to tell if your application is running on a grayscale monitor, 

Color Display since it runs off the same color board. The grayscale monitor is usually driven 

from the red output of the color board, so if two colors have different green and 
blue values but the same red value, they will show up the same on a greyscale 
display. 

To see how your color application will look on a grayscale monitor, temporarily 
set your colormap segment so that the green and blue components of each color- 
map entry are the same as the red component. This will simulate the grayscale 
display on a color monitor. 

Software Double Buffering Sometimes you want to rapidly display different images in an application. If you 

just use the pixwin write operations to display the new image, the redrawing of 
the pixels will be perceptible to the user, even though the operations are fast. 
Instead, you can use a technique called software double -buffering. 

As we have seen, on a color display, there are 8 bits associated with each pixel. 

If you are not using 256 shades at once, then some of these bits are unused. 

What you would like to do is to store values for two or more different images in 
these 8 bits, but only display one set of values at a time. 

The first goal can easily be accomplished using the pw_putattributes ( ) 
routine to restrict writes to a particular set of planes: 



45 Unless you are running with black and white inverted, using the -i option to sunview. 
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pw_putattributes(pw, planes) 
Pixwin *pw; 
int *planes; 



planes is a bitplane access enable mask. Only those bits of the pixel 
corresponding to a 1 in the same bit position of * planes will be affected by 
pixwin operations. If planes is NULL, that attribute value will not be written. 

A corresponding routine is provided to retrieve the value of the access enable 
mask: 

pw_getattributes (pw, planes) 

Pixwin *pw; 
int *planes; 

NOTE Use pw_putattributes ( ) with care, as it changes the internal state of the 
pixwin. The correct usage is to first save the existing bitplane mask by calling 
pw_getattributes ( ) , then call pw_putattributes ( ) , then, when 
done, restore the initial state by calling pw_putattributes ( ) with the saved 
mask. 

The second goal — only displaying what is in some of the planes — is trickier. 
There is no way to tell the hardware to only look at the values in some of the 
planes to determine the colors to show. 

What you do instead is modify the colormap so that only values in certain planes 
of the colormap change the color on the display, so in effect only those planes are 
visible. For example, to display two different four-color images you could use 
the colormap shown in the following table. 

Table 7-1 Sample Colormap to Isolate Planes 
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Using Software Double 
Buffering For Smooth 
Animation 



Pixel Value 


Colormap A 
(Only upper planes 
are “visible”) 


Colormap B 
( Only lower planes 
are “ visible ” 


0 0 0 0 


blue 


blue 


0 0 0 1 


blue 


red 


0 0 10 


blue 


green 


0 0 11 


blue 


pink 


0 10 0 


red 


blue 


0 10 1 


red 


red 


0 110 


red 


green 


0 111 


red 


pink 


10 0 0 


green 


blue 


10 0 1 


green 


red 


10 10 


green 


green 


10 11 


green 


pink 


110 0 


pink 


blue 


110 1 


pink 


red 


1110 


pink 


green 


1111 


pink 


pink 



From the above table, you can see that if colormap A is set (using 
pw_putcolormap ( ) ), then no matter what the value in the two lower planes, 
the color displayed is the same; the value in the upper two planes alone controls 
the color. So, if you use this colormap while only enabling the two lower planes 
(by passing pw_putattributes ( ) the value 3 ), then the values you write 
into the lower planes won’t change what is shown. 

When you switch to colormap B, the situation is reversed. Only the values in the 
lower planes affect what is visible. You would then pass 
pw put attributes ( ) the value 12 to write to the upper two planes. The 
two sets of colors need not be the same, so you can switch between two 
different-colored images. 

You would use the same technique to switch between more images and/or to 
display more colors. You can display two different images, each with 16 dif- 
ferent colors, or 8 different monochrome images, or values in between. 

One application of the above technique is to provide smooth animation. To 
move an image across the screen, you must draw it in one location, erase it, and 
redraw it in another. Even on a fast system, the erasing and redrawing is visible. 
You’d like the object to immediately appear in its new position, without disap- 
pearing momentarily. You can do this by alternating two colormaps so that the 
object disappears in its old location and reappears in a new one. This is called 
software double-buffering , because you are using the display planes as alternat- 
ing buffers; as you write to one set of planes, the other set of planes is displayed. 

The colormaps in the table on the preceding page come from the software pro- 
gram animatecolor in Appendix A, Example Programs. This program uses 
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Hardware Double-Buffering 



Be sure to include 
<sunwindow/pw_dblbuf . h> in 
your double-buffering programs. 
They may will not compile without it. 



software double buffering to animate some squares. The routines it uses to create 
the two colormaps and swap between them are complicated, but can be reused in 
more sophisticated graphics applications. 

The following routines will allow programs to do true hardware double-buffering 
on the cg5 board, which uses the vanilla cg2 device driver. For information on 
the device driver interface, refer the the cgtwo(4S) manual page. 46 color 
framebuffer and on future framebuffers that support double-buffering. 

Double-buffering is treated as an even scarcer resource than colormaps, since 
only one window can be truly double-buffered at any one time. The cursor con- 
trols which window will flip the display buffers. Applications are able to run the 
same code on non-double -buffered displays and it will be as if the double- 
buffering calls were never made. The following code fragment contains proto- 
typical application code. 



. 

Rect rectangle; 

Pixwin *pw; 
rectangle . r_left= 

if (!pw_dbl_get (pw, PW_DBL_AVAIL) ) 

{ ... if program cares ... } 
pw_dbl_access (pw) ; 
while (rendering_frames ) { 

... calculate one frame ... 
pw_lock (pw, &rectangle); 

... render one frame ... 

... may include unlocks and locks ... 
pw_dbl_flip (pw); 
pw_unlock (pw); 

} 

pw_dbl_release (pw); 

\ 



The notion of the “active” double-buffering window is important. There is at 
most one active window at a time. If the cursor is in a double-buffering window, 
then the window is the active double-buffering window. If the cursor leaves the 
active window, that window remains active until the cursor enters another 
double-buffering window. If the active double-buffering window dies, goes 
iconic, or becomes totally obscured, and the cursor is not left in a double- 
buffering window, then the top-most visible double -buffering window becomes 
the active window (if there is one). 

Only the active window will be allowed to write to a single buffer. All other win- 
dows write to both buffers, so that when the display flips to the other buffer, their 
contents remain unchanged. The notion of active will change only during a 
pw_dbl_flip{ ) call. 



46 The eg 5 board is binary compilable with both the Sun-3 Color Board and the Sun-2 Color Board, eg 5 is 
necessary for hardware double-buffering. 
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pw_dbl_access() which resets the window’s data structure so that first frame 
will be rendered to the background. The very first double buffer sets both READ 
and WRITE to the backgound. pw_dbl_access() should only be called when 
ready to actively animate: 

pw_dbl_access (pw) 

Pixwin *pw; 

If the pixwin’ s window has not been accessed for double-buffering then there is 
no change, and both buffers will be written to. 

If the window is marked as accessible for double-buffering and the window is 
“active” , then the frame double-buffering control to whatever this window 
requested with its last pw_dbl_set ( ) call. If there was no pw_dbl_set( ) 
call, then set WRITE and READ to the background. Change the frame buffer 
double-buffering control bits to reflect this. 

If the window is accessible for double-buffering then potentially flip the display. 
The display is flipped only if the window is “active” : pw_dbl_f lip ( ) deter- 
mines if its window has become active: 

pw_dbl_f 1 ip ( pw ) 

Pixwin *pw; 

The flip can be done inside or outside of a lock region although it may be prefer- 
able to place inside a lock region just before an unlock so that calculations for the 
next frame can proceed even if another window momentarily grabs the lock. The 
flip from one buffer to another is synchronized with the display’s vertical retrace. 

The procedure 

pw_db l_r e 1 ea s e ( pw ) 

Pixwin *pw; 

signifies the end of double -buffering by the window associated with the pixwin. 
Call pw_dbl_release ( ) as soon as your program has completed a section of 
active animation. This procedure will copy the foreground buffer to the back- 
ground. Because of this, it is important to leave the animation loop after a 
pw_dbl_f lip ( ) has been done and before drawing the next frame has started. 
Otherwise, the window will contain an incomplete buffer image after the release. 

SunView provides the ability for an actively double-buffering window to write to 
both buffers. For example, the instrument gauge readings can be set in a real- 
time simulator. If pw is not the active double buffer, the frame buffer control bits 
are not changed. The procedure and the attributes that it may use are discussed 
below. 

pw_dbl_set(pw, attributes) 

Pixwin *pw; 

<attribute-list> attributes; 
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Table 7-2 Pixmn-Level set Attributes 




The attribute value returned from pw dbl get ( ) does not reflect the true state 
of double buffering hardware. This is especially true if the active double buffer 
is not this pixwin. The procedure and the attributes that is uses are given below. 

pw_dbl_get(pw, attribute) 

Pixwin *pw; 

Pw_dbl_attribute attribute; 

Table 7-3 Pixwin-Level get Attributes 




7.6. Plane Groups and the The Sun- 3/1 10, Sun-3/60, and Sun-4/ 1 10 color machines use the 

eg four Frame Buffer eg f our ( 4 s ) 47 frame buffer, which supports multiple “plane groups.” Each 

displays either 24-bit color or black and white. In the former case its color is 
determined by a value in an 8-bit color buffer; in the latter case, a monochrome 
buffer called the overlay plane. 

Whether the pixel displays in color or black/white is controlled by the value for 
the pixel in the enable plane , a third plane. If the value in the enable plane is not 
set, then the 8-bit deep value in the color buffer is passed to the circuitry that pro- 
duces the color from the lookup table. If it is set, then the overlay plane deter- 
mines the pixel’s color (black or white). The effect is like having a color and 
monochrome display in one, with the enable plane determining which is shown 
in each pixel. 

In fact, in the color Sun- 3/60 and Sun-4/110 plane group implementations, you 
can set the colors in the overlay plane to other that black and white. There are 
only two colors in the overlay plane since it is only one-bit deep, but they can 
have colors other than black and white assigned to them. 

Such sets of buffers are referred to as plane groups. 
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Sun View and Plane Groups At the pixrect level it is possible to manipulate the three plane groups of multiple 

plane group framebuffers directly. At the SunView level, some decisions have 
been made for you. Raster operations in the overlay plane are faster than in the 
color plane, so SunView objects which only use the foreground and background 
colors such as frames, text subwindows, panels, cursors, menus, etc. all try to run 
in the overlay plane. If you set the foreground and background explicitly using 
the techniques explained in Changing Colors from the Command Line above, or 
if you have told sunview to run in the color buffer only by giving it the com- 
mand line argument - 8bit_color_only , then these objects will run in the 
color plane. 

However, canvases and graphics subwindows default to using the color plane 
group whenever possible, on the assumption that you want to draw in color. If 
this is not the case, then you may find that your application runs faster if you hint 
to these subwindows to use the overlay plane: 

□ For canvases, set the attribute CANVAS_FAST_MONO, either when creating 
the canvas or later, as in: 



window_set ( canvas , CANVAS_FAST_MONO , TRUE, 0); 

l 



If your application uses scrollbars, then you need to set 

CANVAS _F AS T_MONO before you create the canvas’ scrollbars, since they 

share the canvas' pixwin. 



□ For graphics subwindows in old-style SunWindows applications, use the 
pixwin call pw_use_f ast_monochrome (pw) as follows: 



r 








pw_use_f ast_monochrome ( gf x->gf x_pixwin) ; 




V 




/ 



Both calls affect only multiple plane group displays, so it is safe and desirable to 
put them in any Sun application that uses monochrome canvases or graphics 
subwindows. Again, if the user gives the appropriate command line arguments, 
canvases and graphics subwindows will run in the color plane regardless of these 
calls. 

“Glitches” Visible when Using For performance reasons, the cursor image is only written in the plane group of 

Plane Groups the window under it. So, if the cursor’s hot spot is in a black and white window 

in the overlay plane and there is an adjacent color window, that part of its image 
that would lie over the color window is invisible, since it is drawn in the overlay 
plane but the enable plane is still showing the value in the color buffer. The 
same disappearance applies in the reverse situation. 

When menus are drawn, the enable plane is set so that they are visible. 
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sunview and Plane Groups 



It is possible to direct sunview(l) to only use the color buffer or the overlay 
plane; it is also possible to start up a second copy of sunview in the other plane 
group, and switch between them using switcher (1) or - 
ad j acentscreens(l). Consult these programs’ manual pages for more infor- 
mation. 
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8 



Summary Tables 



Text Subwindows 



This chapter describes the text subwindow package, which you can use by 
including the file <suntool/textsw . h>. 

Figure 8-1 is a text subwindow. A text subwindow allows a user or client to 
display and edit a sequence of ASCII characters. These characters are stored in a 
file or in primary memory. Its features range from inserting into a file to search- 
ing for and replacing a string of text or a character. 

Figure 8-1 Text Subwindow 



EE 








Scratch window 




n 







| File * k 


mm 




Display 

Find 

Extras 


Undo ■; 


Copy 1 

Paste | 

Cut | 




Show Clipboard"* j 

Copy, then Paste 5 







To give you a feeling for what you can do with text subwindows, overleaf there 
is a list of the available text subwindow attributes and functions. Many of these 
are discussed in the rest of this chapter and elsewhere (use the Index to check). 
All are briefly described with their arguments in the text subwindow summary 
tables in Chapter 19, SunView Interface Summary : 

□ the Text Subwindow Attributes, 

□ the Textsw_action Attributes, 

□ the Textsw_status Values, 

□ the Text Subwindow Functions. 
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Text Subwindow Attributes 



TEXTSW_ADJUST_IS_PENDING_DELETE 

TEXTSW_AGAIN_RECORDING 

TEXTSW_AUTO_INDENT 

TEXTSW_AUTO_SCROLL_BY 

TEXTSW_BLINK_CARET 

TEXTSW_BROWSING 

TEXTSW_CHECKPOINT_FREQUENCY 

TEXTSW_CLIENT_DATA 

TEXTSW_CONFIRM_OVERWRITE 

TEXTSW_CONTENTS 

TEXTSW_CONTROL_CHARS_USE_FONT 

TEXTSW_DISABLE_CD 

TEXTSW_DISABLE_LOAD 

TEXTSW_EDIT_COUNT 

TEXTSW_FILE 

TEXTSW_FILE_CONTENTS 

TEXTSW_FIRST 

TEXTSW_FIRST_LINE 

TEXTSW_HISTORY_LIMIT 

TEXTSW IGNORE LIMIT 



TEXTSW_INSERT_FROM_FILE 

TEXTSW_INSERT_MAKES_VISIBLE 

TEXTSW_INSERTION_POINT 

TEXTSW_LEFT_MARGIN 

TEXTSWJLENGTH 

TEXTSW_LINE_BREAK_ACTION 

TEXTSW_LOWER_CONTEXT 

TEXTSW_MEMORY_MAXIMUM 

TEXTSW_MENU 

TEXTSW_MODIFIED 

TEXTSW_MULTI_CLICK_SPACE 

TEXTSW_MULTI_CLICK_T IMEOUT 

TEXTSW_NOTIFY_PROC 

TEXTSW_READ_ONLY 

TEXTSW_SCROLLBAR 

TEXTSW_STATUS 

TEXTSW_STORE_CHANGES_FILE 

TEXTSW_STORE_SELF_IS_SAVE 

TEXTSW_UPDATE_SCROLLBAR 

TEXTSW UPPER CONTEXT 



Textsw_ 


action Attributes 


TEXTSW_ACTION_CAPS_LOCK 


TEXTSW_ACT ION_TOOL_CLOSE 


TEXTSW_ACT I ON_CHANGED_DI RECTORY 


TEXTSW_ACTION_TOOL_DESTROY 


TEXTSW_ACTION_EDITED_FILE 


TEXTSW_ACTION_TOOL_QUIT 


TEXTSW_ACTION_EDITED_MEMORY 


TEXTSW_ACTION_TOOL_MGR 


TEXTSW_ACT ION_FI LE_I S_READONLY 
TEXTSW_ACTION_LOADED_FILE 


TEXTSW_ACTION_USING_MEMORY 




Revision A, of March 27, 1990 








Chapter 8 — Text Sub windows 119 



Text Subwindow Functions 
textsw_add_mark( textsw, position, flags) 
textsw_append_f ile_name ( textsw, name ) 
textsw_delete( textsw, first, last_plus_one) 
textsw_edit( textsw, unit, count, direction) 
textsw_erase( textsw, first, last_plus_one) 
textsw_f ile_lines_v is ible( textsw, top, bottom) 

textsw_find_bytes (textsw, first, last_plus_one , buf, buf_len, flags) 
textsw_f ind_mark (textsw, mark) 
textsw_f irst ( textsw) 

textsw_index_f or_f ile_line ( textsw , 1 ine ) 
textsw_insert( textsw, buf, buf_len) 
textsw_match_bytes ( textsw, first, last_plus_one , 

start_sym, start_sym_len, end_sym, end_sym_len, field_flag) 

textsw_next ( textsw) 

textsw_normalize_view( textsw, position ) 
textsw_poss ibly_normalize ( textsw, pos it ion ) 
textsw_remove_mark( textsw, mark) 

textsw_replace_bytes (textsw, first, last_plus_one , buf, buf_len) 

textsw_reset( textsw, x, y) 

textsw_save( textsw, x, y) 

textsw_screen_line_count ( textsw) 

textsw_scroll_lines ( textsw, count ) 

textsw_set_selection( textsw, first, last_plus_one , type) 
textsw_store_file( textsw, filename, x, y) 
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This section introduces the basic concepts of a text subwindow. 

You create a text subwindow the same way that you create any SunView window 
object, by calling the window creation routine with the appropriate type parame- 
ter: 

Textsw textsw; 

textsw = window_create(base_frame, TEXTSW, attributes , 0); 

k 

The attributes in the above call constitute an attribute list which is discussed in a 
Section later in this chapter, titled Attribute -based Functions. 

Most attributes are orthogonal; thus you usually need not worry about their order. 
However, in a few cases the attributes in a list may interact, so you need to be 
careful to specify them in a particular order. Such cases are noted in the sections 
which follow. 48 In particular, you must pass TEXTSW_STATUS first in any call 
to window_create ( ) or window_set ( ) if you want to find the status after 
setting some other attribute in the same call. 

The contents of a text subwindow are a sequence of characters. At any moment, 
each character can be uniquely identified by its position in the sequence (type 
Textsw__index). Editing operations, such as inserting and deleting text, cause 
the index of any particular character to change over time. The valid indices are 0 
through length- 1 inclusive, where length is the number of characters currently in 
the text subwindow, returned by the TEXTSW_LENGTH attribute. 

The text subwindow has a notion of the current index after which the next char- 
acter will be inserted at any given moment. This is called the insertion point. A 
caret is drawn on the screen immediately after this index to give the user a visual 
indication of the insertion point. 

Getting a Text Selection A text selection is made by the user, and it is indicated on the screen with 

reverse-video highlighting. A text subwindow function or procedure is not used 
to determine which window has the current selection or to retrieve information 
contained in a text subwindow. Instead, these functions are carried out by the 
Selection Service. For an example of how this is done, refer to Section 16, The 
Selection Service. 

Editing a Text Subwindow A text subwindow may be edited by the user, or by a client program. When you 

create a text subwindow, by default the user can edit it. By using the special 
attributes discussed in this section, the client program can edit the subwindow. 
These edits are then stored in /tmp/text Process-id.Counter. 

The following five sections explain the functions and attributes that you will use 
to load, read, write, edit, and finally save a text file. 



8.1. Text Subwindow 
Concepts 

Creating a Subwindow 



Attribute Order 

Determining a Character’s 
Position 



48 For a discussion of attribute ordering in general, see Section 4.8 .Attribute Ordering. 
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8.2. Loading a File You can load a file into a textsw by using textsw file, as in: 




Keep in mind, that if the existing text has been edited, then these edits will be 
lost. To avoid such loss, first check whether there are any outstanding edits by 
calling: 




The above call to window_set ( ) will load the new file with the text posi- 
tioned so that the first character displayed has the same index as the first charac- 
ter that was displayed in the previous file — which is probably not what you 
want. To load the file with the first displayed character having its index specified 
by position, use the following: 




NOTE The order of these attributes is important. Because attributes are evaluated in 
the order given, reversing the order would first reposition the existing file, then 
load the new file. This would cause an unnecessary repaint, and mis-position the 
old file, if it was shorter than position. For a full discussion of attribute ord- 
ering, see Section 8.5. 

Checking the Status of the Both of the above calls blindly trust that the load of the new file was successful. 

Text Subwindow This is, in general, a bad idea. To find out whether the load succeeded, and if 

not, why not, use the following call: 




where status is declared to be of type Textsw status. 

NOTE The TEXTSW_STATUS attribute and handle must appear in the attribute list 
before the operation whose status you want to determine. 

Textsw status Value The valid values for such a variable are enumerated in the following table, where 

the common prefix TEXTSW_STATUS_ has been removed. For example, OKAY 
in the table is actually TEXTSW_STATUS_OKAY. 
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Table 8-1 Textsw status Values 



Value 


Description 


TEXTSW_STATUS_OKAY 


The operation encountered no problems. 


TEXTSW__STATUS_BAD_ATTR 


The attribute list contained an illegal or unrecognized attribute. 


TEXTSW_STATUS_BAD_ATTR_VALUE 


The attribute list contained an illegal value for an attribute, 
usually an out of range value for an enumeration. 


TEXTSW_STATUS_CANNOT_ALLOCATE 


A call to calloc(2) or malloc(2) failed. 


TEXTSW_STATUS_CANNOT_OPEN_INPUT 


The specified input file does not exist or cannot be accessed. 


TEXTSWJSTATUS_CANNOT_INSERT_FROM_FILE 


The operation encountered a problem when trying 
to insert from file. 


TEXTSW_STATUS_OUT_OF_MEMORY 


The operation ran out of memory while editing in memory. 


TEXTSW_STATUS_OTHER_ERROR 


The operation encountered a problem not covered by any of 
the other error indications. 



To insert text into a text subwindow at the current insertion point, call: 

Textsw_index 

textsw_insert( textsw, buf, buf_len) 

Textsw textsw; 
char *buf ; 
int buf_len; 

The return value is the number of characters actually inserted into the text 
subwindow. This number will equal buf _len unless either the text subwindow 
has had a memory allocation failure, or the portion of text containing the inser- 
tion point is read only. The insertion point is moved forward by the number of 
characters inserted. 

NOTE This routine does not do terminal-style interpretation of the input characters. 

Thus “editing” characters (such as CTRL-H or DEL for character erase, etc.) are 
simply inserted into the text subwindow rather than performing edits to the exist- 
ing contents of the text subwindow. In order to do terminal- style emulation, you 
must pre-scan the characters to be inserted, and invoke textsw_edit ( ) where 
appropriate, as described in the next section. 
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Subwindow 
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Insertion Point 



Positioning to End of Text 

NOTE 



8.4. Reading from a Text 
Subwindow 



The attribute TEXTSW_INSERTI0N_P0INT is used to interrogate and to set 
the insertion point. For instance, the following call determines where the inser- 
tion point is: 



Textsw_index point; 

point = (Textsw_index)window_get( textsw, 

TEXTSW_INSERTION_POINT) ; 

k ) 



whereas the following call sets the insertion point to be just before the third char- 
acter of the text: 

window_set ( textsw, TEXTSW_INSERTION_POINT , 2, 0); 

^ 



To set the insertion point at the end of the text, set 

TEXTSW_INSERTION_POINT to the special index TEXTSW_INFINITY. 

This call does not ensure that the new insertion point will be visible in the text 
subwindow, even if the textsw_insert_makes_visible attribute is 
TRUE. To guarantee that the caret will be visible afterwards, you should call 
textsw_possibly_normalize( ). 

Many applications that incorporate text subwindows never need to read the con- 
tents of the text directly from the text subwindow. Often, this is because the text 
subwindow is only being used to display text to the user. 

Even when the user is allowed to edit the text, some applications simply wait for 
the user to perform some action that indicates that all of the edits have been 
made. They then use either texts w_s a ve ( ) or textsw_store_f ile( ) to 
place the text in the file. The text can then be read via the usual file input utili- 
ties, or the file itself can be passed off to another program. 

It is, however, useful to be able to directly examine the text in the text subwin- 
dow. You can do this using the TEXTSW_CONTENTS attribute. The following 
code fragment illustrates how to use TEXTSW_CONTENTS to get a span of char- 
acters from the text sub window. It gets the 1000 characters beginning at position 

500 out of the text subwindow and places them into a null-terminated string. 



#def ine TOJREAD 1000 

char buf [ TO_READ+l ] ; 

Textsw_index next_pos; 

next_pos = (Textsw_index) 

window_get (textsw, TEXTSW_CONTENTS , 500, buf, TO_READ) ; 

if (next_pos != 500+TO_READ) { 

Error case 
} else 

buf [ TO_READ] = '\ 0 ' ; 

^ ) 
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8.5. Editing the Contents of 
a Text Subwindow 



Removing Characters 



Emulating an Editing 
Character 



The file or memory being edited by a text subwindow is referred to as the back- 
ing store. Several attributes and functions are provided to allow you to manipu- 
late the backing store of a text subwindow. 49 This section describes the pro- 
cedures and attributes that you can use to edit a text subwindow. 



You can remove a contiguous span of characters from a text subwindow by cal- 
ling: 

Textsw_index 

textsw_delete( textsw, first, last_plus_one) 

Textsw textsw; 

Textsw_index first, last_plus_one; 

first specifies the first character of the span that will be deleted, while 
last_plus_one specifies the first character after the span that will not be 
deleted, first should be less than, or equal to, last_plus_one. To delete 
to the end of the text, pass the special value TEXTSW_INFINITY for 
last_plus_one. 

The return value is the number of characters deleted, and is last_plus_one 
- f irst, unless all or part of the specified span is read-only. In this case, only 
those characters that are not read-only will be deleted, and the return value will 
indicate how many such characters there were. If the insertion point is in the 
span being deleted, it will be left at f irst. 

A side-effect of calling textsw_delete ( ) is that the deleted characters 
become the contents of the global Clipboard. To remove the characters from the 
textsw subwindow without affecting the Clipboard, call: 

Textsw_index 

textsw_erase( textsw, first, last_plus_one) 

Textsw textsw; 

Textsw_index first, last_plus_one; 

Again, the return value is the number of characters removed, and 
last_plus_one can be TEXTS W_INF INI TY. 

Both of these procedures will return 0 if the operation fails. 

You can emulate the behavior of an editing character, such as CTRL-H, with 
textsw_edit ( ) : 

Textsw_index 

textsw_edit( textsw, unit, count, direction) 

Textsw textsw; 

unsigned unit, count, direction; 



49 Note that the edit log maintained by the text subwindow package is reset on each operation affecting the 
backing store. For a description of the edit log, see the discussion at the end of Editing the Contents of a Text 
Subwindow. 
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Replacing Characters 



Depending on the value of unit, this routine will erase either a character, a 
word, or a line. Set unit to: 

□ TEXTSW_UNIT_I S CHAR to erase individual characters, 

□ TEXTSW_UNIT_I S WORD to erase the span of characters that make up a 
word (including any intervening white space or other non-word characters), 
or 

□ TEXTSW_UNIT_IS_LINE to erase all characters in the line on one side of 
the insertion point. 

If the direction parameter is 0, the operation will affect characters after the 
insertion point, otherwise it will affect characters before the insertion point. 

The number of times the operation will be applied is determined by the value of 
the count parameter. Set it to one to do the edit once, or to a value greater than 
one to do multiple edits in a single call. textsw_edit ( ) returns the number 
of characters actually removed. 

For example, suppose you want to interpret the function key [ F7 1 as meaning 
“delete word forward”. On receiving the event code for the ( F7 1 key going up, 
you would make the call: 

text sw_edit ( textsw , TEXTSW_UNIT_IS_WORD, 1 , 0); 

's. J 



While a span of characters may be replaced by calling textsw_erase ( ) fol- 
lowed by textsw_insert ( ) , character replacement is done most efficiently 
by calling: 

Textsw_index 

textsw_replace_by tes ( textsw, first, last_plus_one, buf, buf_len) 
Textsw textsw; 

Textsw_index first, lastplusone ; 
char *buf ; 

int buf_len; 

The span of characters to be replaced is specified by first and 
last_plus_one, just as in the call to textsw erase ( ) . The new charac- 
ters are specified by buf and buf _len, just as in the call to 
textsw_insert ( ) . Once again, if last_plus_one is 
TEXTSW_INFINITY, the replace affects all characters from first to the end 
of the text. If the insertion point is in the span being replaced, it will be left at 
first + buf_len. 

The return value is the net number of bytes inserted. The number is negative if 
the original string is longer than the one which replaces it. If a problem occurs 
when an attempt is made to replace a span, then it will return an error code of 0. 

textsw_replace_bytes ( ) , like textsw_erase ( ) , does not put the 
characters it removes on the global Clipboard. 
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The Editing Log 



Which File is Being Edited? 



Interactions with the File 
System 



All text subwindows allow the user to undo editing actions. In order to imple- 
ment this feature, the text subwindow package keeps a running log of all the 
edits. If there is a file associated with the text subwindow, this log is kept in a 
file in the /tmp directory. 

This file can grow until this directory runs out of space. To limit the size of the 
edit log and to avoid filling up all of tmp the user can set the text wrap around 
size in the def aultsedit(l) Tty I text _yvraparound_size or use the attribute 
TEXTS W_WRAPAROUND_S I Z E. If there is no associated file, the edit log is 
kept in memory, and the maximum size of the log is controlled by the attribute 
TEXTSW_MEMORY_MAXIMUM, which defaults to 20,000 bytes. 

Unfortunately, once an edit log kept in memory has reached its maximum size, 
no more characters can be inserted into or removed from the text subwindow. In 
particular, since deletions, as well as insertions, are logged, space cannot be 
recovered by deleting characters. 

It is important to understand how the edit log works because you may want to use 
a text subwindow with no associated file to implement a temporary scratch area 
or error message log. If such a text subwindow is used for a long time, the 
default limit of 20,000 bytes may well be reached, and it will be impossible for 
either the user or your code to insert any more characters even though there may 
be only a few characters visible in the text sub window. Therefore, it is recom- 
mended to set TEXTSW_MEMORY_MAXIMUM much higher, say to 200,000. 

To find out which file the text subwindow is editing, call: 
int 

tex t sw_append_f ile_name ( text sw , name ) 

Textsw textsw; 
char *name; 

If the text sub window is editing memory, then this routine will return a non-zero 
value. Otherwise, it will return 0, and append the name of the file to the end of 
name. 

If a text subwindow is editing a file called my file and the user chooses ‘Save 
Current File’ from the sub window’s menu (or client code invokes 
textsw_save ( ) ), the following sequence of file operations occurs: 

□ myf ile is copied tomyf ile% 

□ The contents of my f ile % are combined with information from the edit log 
file (/tmp/Text Process-id . Counter ) and written over myf ile (thereby 
preserving all its permissions, etc). 

□ The edit log file is removed from /tmp. 

If myf ile is a symbolic link to ../somedir / otherf ile, then the backup file 
is created as ../some_dir/ot.herf ile%. 
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8.6. Saving Edits in a 
Subwindow 



Storing Edits 



Discarding Edits 



Keep in mind that the user can change the current directory by selecting ‘Load 
File’ or ‘Set Directory’ from the text subwindow menu. If my f ile is a relative 
path name, then the copy to my file % and the save take place in the current 
directory. 

To save any edits made to a file currently loaded into a text subwindow call: 
unsigned 

textsw_save( textsw, locx, locy) 

Textsw textsw; 
int locx, locy; 

locx and locy are relative to the upper left comer of the text subwindow and 
are used to position the upper left comer of the alert should the save fail for some 
reason — usually they should be 0. The return value is 0 if and only if the save 
succeeded. 

The text subwindow may not contain a file, or the client may wish to place the 
edited version of the text (whether or not the original text came from a file) in 
some specific file. To store the contents of a text subwindow to a file call: 

unsigned 

textsw_store_f ile ( textsw, filename, locx, locy) 

Textsw textsw; 
char * filename; 
int locx, locy; 

Again, locx and locy are used to position the upper left comer of the message 
box. The return value is 0 if and only if the store succeeded. 

NOTE By default, this call changes the file that the text subwindow is editing, so that 
subsequent saves will save the edits to the new file. To override this policy, set 
the attribute textsw_store_changes_file to false. 

To discard the edits performed on the contents of a text subwindow, call: 
void 

textsw_reset( textsw, locx, locy) 

Textsw textsw; 
int locx, locy; 

locx and locy are as above. Note that if the text subwindow contains a file 
which has not been edited, the effect of textsw reset is to unload the file 
and replace it by memory provided by the text subwindow package; thus the user 
will see an absolutely empty text subwindow. Alternatively, if the text subwin- 
dow already was editing memory then another, untouched, piece of primary 
memory will be provided and the edited piece will be deallocated. 

The rest of this chapter describes the other functions that are available for text 
subwindows. These features include setting the contents of a subwindow, setting 
the primary selection, and how to deal with multiple or split views. 
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8.7. Setting the Contents of You may want to set the initial contents of a text subwindow that your applica- 
a Text Subwindow tion uses. For example, the SunView mailtool sets the initial contents of the 

composition window to come up with the headings To, Subject, and so on. 

To set the initial contents of a text subwindow, use one of three attributes: 
TEXTSW_INSERT_FROM_FILE, TEXTSW_FILE_CONTENTS, and 
TEXTSW_CONTENTS. Each attribute is illustrated in code fragments given 
below. 



TEXTS W_FILE_CONTENTS The attribute TEXTSW_FlLE_CONTENTS makes it possible for a client to ini- 
tialize the text subwindow contents from a file yet still edit the contents in 
memory. The user can return a text subwindow to its initial state after an editing 
session by choosing ‘Undo All Edits’ in the text menu. 

The following code fragment shows how you would use this attribute. 


Textsw textsw; 

char *filename; 

Textswindex pos; 

window_set ( textsw, 

TEXTSW_FILE CONTENTS , filename, 

TEXTSW_FIRST, pos, 

0 ); 

l 



When the client calls the undo routine and filename is not a null string, then it 
will initialize the memory used by the text subwindow with the contents of the 
file specified by filename. 

When the client calls the undo routine and the filename is a null string, then it 
will initialize the memory used by the text subwindow with the previous contents 
of the text subwindow. 

TEXTS W_CONTENTS TEXTSW_CONTENTS lets you insert a text string from memory, instead of a file, 

into the text sub window. The default for this attribute is NULL. 

If you use window_create ( ) with this attribute, then it will specify the initial 
contents for a non-file text subwindow. 

If you use window_set ( ) with this attribute it will set the contents of a win- 
dow as in: 



window_set( textsw, TEXTSW_CONTENTS, "text", 0); 

l 



If you use window get ( ) with this attribute, then you will need to provide 
additional parameters as in: 



window_get (textsw, TEXTSW_CONTENTS , pos, buf, buf_len) 
v 



The return value is the next position to be read. The buffer array 
#sun Revision A, of March 27, 1990 
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buf [ 0. . .buf _len - 1 ] is filled with the characters from textsw beginning at 
the index pos, and is null-terminated only if there were too few characters to fill 
the buffer. 

TEXT S W_I N S ERT_FROM_F I LE TEXTSW_INSERT_FR0M_FILE allows a client to insert the contents of a file 

into a text subwindow at the current insertion point. It is the programming 
equivalent of a user choosing ‘Include File’ from the text menu. 

The following code fragment is a sample of using this attribute. 

. 

Textsw textsw; 

Textsw_status status; 

window_set ( textsw, 

TEXTSW_STATUS, Sstatus, 

TEXTSW_INSERT_FROM_FI LE , filename, 

0 ) ; 

v J 



Three status values may be returned for this attribute when the argument 
TEXTS W_STATUS is passed in the same call to window_create ( ) or 
window_set ( ) : 

□ TEXT S W_S TATU S_OKAY — the operation was successful. 

□ TEXT S W_STATU S_C ANNOT_I N S ERT_FROM_F I LE — the Operation 
failed 

□ TEXTSW_STATUS_OUT_OF_MEMORY — the function cannot insert the 
text, because it ran out of memory 

8.8. Positioning the Text 
Displayed in a Text 
Subwindow 



Usually there is more text managed by the text subwindow than can be displayed 
all at once. As a result, it is often necessary to determine the indices of the char- 
acters that are being displayed, and to control exactly which portion of the text is 
being displayed. 



Screen Lines and File Lines When there are long lines in the text it is necessary to draw a distinction between 

two different definitions of “line of text.” 

A screen line reflects what is actually displayed on the screen. A line begins 
with the leftmost character in the subwindow and continues across until either a 
newline character or the right edge of the subwindow is encountered. A file line , 
on the other hand, can only be terminated by the newline character. It is defined 
as the span of characters starting after a newline character (or the beginning of 
the file) running through the next newline character (or the end of the file). 

Whenever the right edge of the subwindow is encountered before the newline, if 
TEXTSW_LINE_BREAK_ACTION is TEXTS W_WR AP_ AT_C H AR , the next 
character and its successors will be displayed on the next lower screen line. In 
this case there would be two screen lines, but only one file line. From the per- 
spective of the display there are two lines; from the perspective of the file only 
one. If, on the other hand TEXTSW_LlNE_BREAK_ACTlON is 
TEXTSW_WRAP_AT_WORD, the entire word will be displayed on the next line. 
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Absolute Positioning 



Relative Positioning 



Unless otherwise specified, all text subwindow attributes and procedures use the 
file line definition. 

NOTE Line indices have a zero-origin, like the character indices; that is, the first line 
has index 0, not 1. 

Two attributes are provided to allow you to specify which portion of the text is 
displayed in the text sub window. 

Setting the attribute TEXTSW_FIRST to a given index causes the first character 
of the line containing the index to become the first character displayed in the text 
subwindow. Thus the following call causes the text to be positioned so that the 
first displayed character is the first character of the line which contains index 
1000. This call only positions one view at a time: 



r 








window set(textsw, TEXTSW_FIRST, 1000, 0); 








/ 



To position all of the views in a text subwindow, use the attribute 
TEXTS W_FOR_ALL_VIEWS as in the following call: 





window_set( textsw, TEXTSW_FOR_ALL_VIEWS, TRUE, 


> 




TEXTSW_FIRST, 1000, 0); 








J 



Conversely, the following call retrieves the index of the first displayed character: 

index = (Textsw_index)window_get (textsw, TEXTSW_FIRST) ; 

V 



A related attribute, useful in similar situations, is TEXTSW_FIRST_LINE. 
When used in a call on window_set ( ) or window_get ( ) , the value is a 
file line index within the text. 

You can determine the character index that corresponds to a given line index 
(both zero-origin) within the text by calling: 

Textsw_index 

textsw_index_for_f ile_line( textsw, line) 

Textsw textsw; 
int line; 

The return value is the character index for the first character in the line, so char- 
acter index 0 always corresponds to line index 0. 

To move the text in a text subwindow up or down by a small number of lines, 
call the routine: 

void 

textsw_scroll_lines ( textsw, count) 

Textsw textsw; 
int count; 

A positive value for count causes the text to scroll up, just as if the user had 
used the left mouse button in the scrollbar, while a negative value causes the text 
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to scroll down, as if the user had used the right mouse button in the scrollbar. 

How Many Screen Lines are When calling textsw_scroll_lines ( ) you may want to know how many 
in the Sub window? screen lines are in the text subwindow. You can find this out by calling: 

int 

textsw_screen_line_count ( textsw) 

Textsw textsw; 



Which File Lines are Visible? Exactly which file lines are visible on the screen is determined by calling: 

void 

textsw_file_lines_visible( textsw, top, bottom) 

Textsw textsw; 
int *top, * bottom; 

This routine fills in the addressed integers with the file line indices of the first and 
last file lines being displayed in the specified text subwindow. 

Guaranteeing What is Visible To ensure that a particular line or character is visible, call: 

void 

textsw_possibly__normalize( textsw, position) 

Textsw textsw; 

Textsw_index position; 

The text subwindow must be displayed on the screen, before this function will 
work. 

If the character at the specified position is already visible, then this routine 
does nothing. If it is not visible, then it repositions the text so that it is visible 
and at the top of the subwindow. 

If a particular character should always be at the top of the subwindow, then cal- 
ling the following routine is more appropriate: 

void 

textsw_normalize_view( textsw, position) 

Textsw textsw; 

Textsw_index position; 

Most of the programmatic editing actions do not update the text subwindow to 
display the caret, even if TEXTSW_I NS ERT_MAKES VISIBLE is set. If you 

want to ensure that the insertion point is visible, call something like 


t ex t sw_pos s ibly_norma 1 ize( textsw, 

(Textsw_index) window_get ( textsw, TEXTSW_INSERTION_JPOINT ) ; 
— 



Ensuring that the Insertion Point 
is Visible 
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8.9. Finding and Matching 
a Pattern 



Matching a Span of 
Characters 



Matching a Specific Pattern 



A common operation performed on text is finding a span of characters that match 
some specification. The text subwindow provides several rudimentary pattern 
matching facilities. This section describes two functions that you may call in 
order to perform similar operations. 

To find the nearest span of characters that match a pattern, call: 
int 

textsw_f ind_bytes { textsw, first, last_plus_one, buf, 
buf_len, flags) 

Textsw textsw; 

Textsw_index * first, *last_plus_one; 
char *buf; 

unsigned buf_len; 

unsigned flags; 

The pattern to match is specified by buf and buf_len. The matcher looks for 
an exact and literal match — it is sensitive to case, and does not recognize any 
kind of meta-character in the pattern, first specifies the position at which to 
start the search. If flags is 0, the search proceeds forwards through the text, if 
1 the search proceeds backwards. The return value is -1 if the pattern cannot be 
found, else it is some non-negative value, in which case the indices addressed by 
first and last_plus_one will have been updated to indicate the span of 
characters that match the pattern. 

Another useful operation is to find delimited text. For example, you might want 
to find the starting brace and the ending brace in a piece of code. To find a 
matching pattern, call: 

int 

textsw_match_bytes ( textsw, first, last_plus_one, 

start_sym, start_sym_len, 
end_sym, end_sym_len, field_flag) 

Textsw 
Textsw_index 
char 
int 

unsigned 

f irst stores the starting position of the pattern that you want to search for. 
last_plus_one stores the cursor position of the end pattern. Its value is one 
position past the text. start_sym and end_sym store the beginning position 
and ending position of the pattern respectively. start_sym_len and 
end_sym_len store starting and ending pattern's length respectively. 

Use one of the three field flag values to search for matches: 

TEXTS W_DELIMITER_FORWARD, TEXTS W_DE L I M I T E R_B AC KW ARD , and 
TEXTSW_DELIMITER_ENCLOSE. 

□ TEXTS W_DELIMITER_F0RWARD begins from first and searches for- 

ward until it finds start_sym and matches it forward with end_sym. 



textsw; 

♦first, *last_plus_one; 
*start_sym, *end_sym; 
start_sym_len, end_sym_len; 
f ield_f lag; 
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□ TEXT S w_DE L I M I T ER_B ACKWARD begins from first and searches 
backward for end_sym and matches it backward with start_sym . 

□ TEXTSW_DELIMITER_ENCL0SE begins from first and expands both 
directions to match start_sym and end_sym of the next level. 

If no match is found, then textsw match bytes ( ) will return a value of 
-1. If a match is found, then it will return the index of the first match. 



The following code fragment is an example of finding delimited text. Notice that 
the f ield_f lag value is TEXTSW_DELIMlTER_FORWARD. 



r 


> 


Textsw index first. 


last plus one, pos; 


first = (Textsw index) 


window_get (textsw, TEXTSW_INSERTION POINT); 


pos = textsw match bytes ( textsw, &first, &last plus one, 




strlen ("*/"), 




strlen ( " */" ) , TEXTSW_DELIMITER_FORWARD) ; 


if (pos > 0) [ 




textsw set selection ( textsw , first, last plus one, 1); 


window set(textsw, 


TEXTSW_INSERTION_POINT , last plus one, 0); 


) else 




(void) window bell (textsw) ; 


k 


; 



This code searches forward from f irst until it finds the starting */ and 
matches it forward with the next */. If no match is found, a bell will ring in the 
text subwindow. 

8.10. Marking Positions Often a client wants to keep track of a particular character, or group of characters 

that are in the text subwindow. Given that arbitrary editing can occur in a text 
subwindow, and that it is very tedious to intercept and track all of the editing 
operations applied to a text subwindow, it is often easier to simply place one or 
more marks at various positions in the text subwindow. These marks are 
automatically updated by the text subwindow to account for user and client edits. 
There is no limit to the number of marks you can add. 

A new mark is created by calling: 

Textsw_mark 

textsw_add_mark ( textsw, position, flags) 

Textsw textsw; 

Textsw_index position; 
uns igned f lags ; 

The flags argument is either textsw_mark_defaults or 
TEXTS W_MARK_MOV E_ AT__ I N S E RT . The latter causes an insertion that occurs 
at the marked position to move the mark to the end of the inserted text, whereas 
the former causes the mark to not move when text is inserted at the mark's 
current position. As an example, suppose that the text managed by the text 
subwindow consists of the two lines 





this is the first line 

not this, which is the second 


*\ 






; J 
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Assume a mark is set at position 5 (just before the i in is on the first line) with 
flags of TEXTSW_MARK_MOVE_AT__INSERT. 

When the user selects just before the is (thereby placing the insertion point before 
the /, at position 5) and types an Bh, making the text read 




the mark moves with the insertion point and they both end up at position 6. 

However, if the flags had been TEXTSW_MARK_DEFAULTS , then the mark 
would remain at position 5 after the user typed the h, although the insertion point 
moved on to position 6. 



Now, suppose instead that the user had selected before the this on the first line, 
and typed Kep, making the text read 




In this case, no matter what flags the mark had been created with, it would end 
up at position 8, still just before the i in is. 



If a mark is in the middle of a span of characters that is subsequently deleted, the 
mark moves to the beginning of the span. Going back to the original scenario, 
with the original text and the mark set at position 5, assume that the user deletes 
from the h in this through the e in the on the first line, resulting in the text 




When the user is done, the mark will be at position 1 , just before the e in te. 



The current position of a mark is determined by calling: 

Textsw_index 

textsw_f ind_mark ( textsw, mark) 

Textsw textsw; 

Textsw_mark mark; 

An existing mark is removed by calling: 
void 

textsv_remove_mark ( textsw, mark) 

Textsw textsw; 

Textsw_mark mark ; 

Note that marks are dynamically allocated, and it is the client’s responsibility to 
keep track of them and to remove them when they are no longer needed. 
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8.11. Setting the Primary 
Selection 



The primary selection may be set by calling: 
void 

textsw_set_selection( textsw, first, last_plus_one, type) 
Textsw textsw; 

Textsw_index first, last_plus_one; 
unsigned type; 

A value of 1 for type means primary selection, while a value of 2 means secon- 
dary selection, and a value of 17 is pending delete Note that there is no require- 
ment that all or part of the selection be visible; use 

textsw_possibly_normalize( ) (described previously in Section 8.5, 
Editing the Contents of a Text Subwindow) to guarantee visibility. 



8.12. Dealing with Multiple By using the ‘Split View’ menu operation, the user can create multiple views of 
Views the text being managed by the text subwindow. Although these additional views 

are usually transparent to the client code controlling the text subwindow, it may 
occasionally be necessary for a client to deal directly with all of the views. This 
is accomplished by using the following routines, and the information that split 
views are simply extra text subwindows that happen to share the text of the origi- 
nal text subwindow. 

Textsw 

textsw_f ir st ( textsw) 

Textsw textsw; 

Given an arbitrary view out of a set of multiple views, textsw_f ir st ( ) 
returns the first view (currently, this is the original text subwindow that the client 
created). To move through the other views of the set, call: 

Textsw 

tex tswnext ( textsw ) 

Textsw textsw; 

Given any view of the set, textsw_next ( ) returns some other member of the 
set, or NULL if there are none left to enumerate. The following loop is 
guaranteed to process all of the views in the set: 

for ( textsw=textsw_f irst(anysplit) ; 

♦textsw; 

textsw=textsw_next ( textsw) ) { 
processing involving textsw; 

} 



When you create a text subwindow take into account that your user may split the 
window. If you do something like try to enlarge the window, you will run into 
problems. 
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8.13. Notifications from a The text subwindow notifies its client about interesting changes in the 

Text Subwindow subwindow’s or text’s state by calling a notification procedure. It also calls this 

procedure in response to user actions. If the client does not provide an explicit 
notification procedure by using the attribute TEXTSW_NOTlFY_PROC, then the 
text subwindow provides a default procedure. The declaration for this procedure 
looks like: 

void 

notify_proc( textsw, avlist) 

Textsw textsw; 

Attr_avlist avlist; 

avlist contains attributes that are the members of the Textsw action 
enumeration. 

Your notification procedure must be careful to either process all of the possible 
attributes that it can be called with or to pass through the attributes that it does 
not process to the standard notification procedure. This is important because 
among the attributes that can be in the avlist are those that cause the standard 
notification procedure to implement the Front, Back, Open, Close, and Quit 
accelerators of the user interface. 



Here is an example of a client notify procedure, and a code fragment demonstrat- 
ing how it would be used: 



f 








‘s 


int 


( *def ault_textsw notify) (); 




void 








client 


notify_proc(textsw, attributes) 






Textsw 


textsw; 




{ 


Attr avlist 


attributes ; 




int 


pass_on 


= FALSE; 






Attr avlist 


attrs ; 






for 


(attrs = 


attributes; *attrs; 








attrs = 


attr next(attrs)) { 








switch ((Textsw action )( *attrs ) ) { 








case 


TEXTSW ACTION CAPS LOCK: 








/* Swallow this attribute */ 
ATTR CONSUME ( *attrs) ; 








break ; 










case 


TEXTSW_ACTION_CHANGED DIRECTORY : 








/* Monitor the attribute, don't swallow it */ 
strcpy (currentdirectory, (char *)attrs[l]); 








pass on 
break ; 
default : 


= TRUE; 








pass on 
break ; 

} 


= TRUE; 






] 

if 


(pass on) 






] 




(void) default_textsw notify (textsw, attributes); 




k 








- - - J 
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def ault_textsw_notify = 

(void (*)() )window_get (textsw, TEXTSW_NOTIFY_PROC) ; 
window_set ( textsw, TEXTSW_NOTIFY_PROC , client_notify_proc, 0); 

V 

The Textsw action attributes which may be passed to your notify procedure 
are listed in the following table (duplicated in Chapter 19, SunView Interface 
Summary). Remember that they constitute a special class of attributes which are 
passed to your textsw notification procedure. They are not attributes of the text 
subwindow in the usual sense, and can not be retrieved or modified using 
window_get( ) or window_set ( ). 



Table 8-2 Textsw action Attributes 



Attribute 


Value Type 


Description 


TEXTSW_ACTION_CAPS_LOCK 


boolean 


The user pressed the CAPS-lock function key to change the 
setting of the CAPS-lock (it is initially 0, meaning off). 


TEXTSW_ACTION_CHANGED_DI RECTORY 


char * 


The current working directory for the process has been 
changed to the directory named by the provided string value. 


TEXTSW_ACTION_EDITED_FILE 


char * 


The file named by the provided string value has been edited. 
Appears once per session of edits (see below). 


TEXTSW_ACTION_EDITED_MEMORY 


none 


monitors whether an empty text subwindow has been edited. 


TEXTSW_ACTION_FILE_IS_READONLY 


char * 


The file named by the provided string value does not have 
write permission. 


TEXTSW ACT ION_LOADED_F I LE 


char * 


The text subwindow is being used to view the file named 
by the provided string value. 


TEXTSW_ACTION_TOOL_CLOSE 


(no value) 


The frame containing the text subwindow should become 
iconic. 


TEXTSW_ACTION_TOOL_DESTROY 


Event * 


The tool containing the text subwindow should exit, 
without checking for a veto from other subwindows. 
The value is the user action that caused the destroy. 


TEXT SW_ AC T 1 0 N_ TOO L_QU I T 


Event * 


The tool containing the text subwindow should exit 
normally. The value is the user action that caused 
the exit. 


TEXTSW_ACTION_TOOL_MGR 


Event * 


The tool containing the text subwindow should do the 
window manager operation associated with the 
provided event value. 


TEXT SW_ AC T 1 0 N_US I NG_MEMO RY 


(no value) 


The text subwindow is being used to edit a string stored in 
primary memory, not a file. 
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The attribute TEXTSW_ACTI0N_EDITED_FILE is a slight misnomer, as it is 
given to the notify procedure after the first edit to any text, whether or not it 
came from a file. This notification only happens once per session of edits, where 
notification of TEXTSW_ACTlON_LOADED_FlLE is considered to terminate 
the old session and start a new one. 

NOTE The attribute TEXTS W_ACT I ON__LO ADED_F I LE must be treated very care- 

fully. This is because the notify procedure gets called with this attribute in 
several situations: after a file is initially loaded, after any successful ‘Save 
Current File’ menu operation, after a 'Undo All Edits’ menu operation, and dur- 
ing successful calls to textsw_reset ( ) , textsw_save ( ) and 
textsw_store ( ) . 

The appropriate response by the procedure is to interpret these notifications as 
being equivalent to: 

“The text subwindow is displaying the file named by the provided 
string value; no edits have been performed on the file yet. In addition, 
any previously displayed or edited file has been either reset, saved, or 
stored under another name.” 



#sun 
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Panels 



This chapter describes the panel subwindow package, which you can use by 
including the file <suntool/panel . h>. 

Section 1 provides a non-technical introduction to panels. Section 2 introduces 
the basic concepts and routines needed to use panels. Scrollable panels are 
covered in Section 3. Sections 4 through 9 describe the different types of panel 
items in detail, including examples. 

For examples of complete panels, see the programs filer, image _browser_l and 
image browser _2, which are listed in Appendix A and discussed in Chapter 4, 
Using Windows. 

Quick Reference, Listings and For quick reference, the next two pages are a visual index to the different effects 

Summary Tables possible in panels. After that come lists of the available panel and panel item 

attributes, functions and macros. Many of these are discussed in the rest of this 
chapter and elsewhere (use the Index to check). Finally, tables that summarize 
the usage of panel attributes, functions and macros are in Chapter 19, SunView 
Interface Summary. 

□ the Panel Attributes, 

□ the Generic Panel Item Attributes , 

□ the Choice and Toggle Item Attributes, 

□ the Slider Attributes, 

□ the Text Item Attributes, 

□ the Panel Functions and Macros. 
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Description 

Messages 

Buttons 

Choice (default) 
Choice (custom marks) 

Choice (inverted) 

Choice (current) 

Choice (cycle) 

Choice (dial) 



Example 




This action uill cause unsaved edits to be lost. 



(Reset] 



[ Reset j 



Drawing Mode: Qpoints 8l_ine Qfiectangle Qcircle 0Text 
Drawing Mode: Points ►Line Rectangle Circle Text 



Drawing Mode: 



Points 



Li ne 



Rectangle 



Circle 



Text 



Drawing Mode: Line 
Drawing Mode: CLine 



Rect 




Circle 

Text 



Drawing Mode 
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Description 

Choice (images, menu) 

Choice (images) 
Toggle (vertical) 

Text 

Text (masked) 

Text with menu 

Slider 



Example 




Points 
s/ Line 

Rectangle 

Circle 

Text 



abc 




Format Options: 

S' Long 
□ Reverse 
S' Show all ft les 

Name: Eduard G. Robinson 



Password: ******** 



File: dervish. image 



ESC - Filename completion b 



Load image from fi le 



''S - Store image to file 
'"B - Brouse directory 
A Q - Quit 



Brightness: [75] 



100 
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Description 



Example 



Button with menu 



Introduction 


Plxulns 


Cursors 


SunVleu Model 


Text Subuindous 


Icons 


Wlndous 


Panels 


| Scrollbars 


Canvases 


TTY Subuindous 


Selection Service 


Input 


Menus 


Notlfler 



Manual 



SL 



Buttons with menus 

on scrollable panel 






Panel Attributes 




PANEL_ACCEPT_KEYSTROKE 


PANEL EVENT_PROC 


PANEL_LABEL_BOLD 


PANEL_BACKGROUND_PROC 


PANEL_FIRST_ITEM 


PANEL_LAYOUT 


PANEL BLINK_CARET 
PANEL_C ARET_I TEM 


PANEL ITEM_X_GAP 
PANEL IT EM_Y_GAP 


PANEL_SHOW_MENU 
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Generic Panel Item Attributes 


PANEL_ACCEPT_KEYSTROKE 


PANEL_MENU_CHOICE_IMAGES 


PANEL_CLIENT_DATA 


PANEL_MENU_CHOICE_STRINGS 


PANEL_EVENT_PROC 


PANEL_MENU_CHO I CE_V ALUES 


PANEL_I TEM_RECT 


P ANEL_MENU_T I T LE_F0NT 


PANEL I TEM_X 


PANEL_MENU_TITLE_IMAGE 


PANEL_I TEM_Y 


P ANE L_MENU_T I T LE_STR I NG 


PANEL_LABEL_X 


PANEL_NEXT_I TEM 


PANEL_LABEL_Y 


PANEL_NOT I FY_PROC 


PANEL_LABEL_BOLD 


PANEL_PAINT 


PANEL_LABEL_FONT 


PANEL_PARENT_PANEL 


PANEL_LABEL_IMAGE 


PANEL_SHOW_I TEM 


PANEL_LABEL_STRING 


PANEL_SHOW_MENU 


PANEL_LAYOUT 


PANEL_VALUE_X 


PANEL_MENU_CHOICE_FONTS 


PANEL_VALUE_Y 



Choice and Toggle Item Attributes 


PANEL_CHOICE_FONTS 




PANEL_CHOICE_FONTS 


PANEL_MARK_IMAGE 


PANEL_CHOICE IMAGE 


PANEL_MARK_IMAGES 


PANEL_CHOICE_IMAGES 


PANEL_MARK_X 


PANEL_CHOICE_STRING 


PANEL_MARK_XS 


PANEL_CHOICE_STRINGS 


PANEL_MARK_Y 


PANEL_CHOICE_X 


PANEL_MARK_YS 


PANEL_CHOI CE_XS 


PANEL_MENU_MARK_IMAGE 


PANEL_CHOICE_Y 


PANEL_MENU_NOMARK_IMAGE 


PANEL_CHOICE_YS 


PANEL_NOMARK_IMAGE 


PANEL_CHOI CES_BOLD 


PANEL_NOMARK_I MAGES 


PANEL_DISPLAY_LEVEL 


PANEL_SHOW_MENU_MARK 


PANEL_FEEDBACK 


PANEL_TOGGLE_VALUE 


PANEL_LAYOUT 


PANEL_VALUE 





Slider Item Attributes 




PANEL_MIN_VALUE 


PANEL_SHOW RANGE 


PANEL_VALUE 


PANEL_MAX_VALUE 

PANEL_NOTIFY_LEVEL 


PANEL_SHOW_VALUE 

PANEL_SLIDER_WIDTH 


PANEL_VALUE FONT 
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Text Item Attributes 




PANEL_MASK_CHAR 




PANEL_VALUE_DISPLAY_LENGTH 


PANEL_N0T I F Y_LEVEL 




PANELVALUE 


PANEL_NOTIFY_STRING 

PANEL_VALUE_STORED_LENGTH 




PANEL_VALUE_FONT 



Panel Functions and Macros 

panel_accept_key (object, event) 
panel_accept_menu ( object, event) 
panel_accept_preview ( object , event ) 
panel_advance_caret ( panel ) 
panel_backup_caret ( panel ) 
panel_begin_preview ( object , event ) 
panel_button_image( panel, string, width, font) 
panel_cancel_preview( object, event) 
panel_create_item( panel, item_type, attributes) 
panel_def aul t_handle_event ( object , event ) 
panel_destroy_item( item) 
panel_each_item( panel, item) 
panel_event( panel, event) 

panel_get( item, attribute [ , optional_arg] ) 
panel_get_value( item) 

panel_paint ( panel_ob j ect , paint_behavior ) 
panel_set ( item, attributes) 
panel_set_value( item, value) 
panel_text_notify ( item, event) 
panel_update_preview ( ob j ect , event ) 
panel_update_scrolling_size (panel ) 
panel_window_event ( panel , event ) 
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9.1. Introduction to Panels Panels contain items through which the user interacts with a program. Panels are 
and Panel Items quite flexible; you can use them to model a variety of things, including: 

□ a form consisting mainly of text items; 

□ a message window containing status or error messages; 

□ a complex control panel containing items and menus of many types. 

Panels need not be limited to the size of the subwindow they appear in. By 
attaching scrollbars to a panel, you can show a large panel within a smaller 
subwindow. The user can then bring the area of interest into view by means of 
the scrollbars. 

There are six basic types of panel items: messages, buttons, choices, toggles, 
text and sliders. Items are made up of one or more displayable components. One 
component shared by all item types is the label. An item label is either a string 
or a graphic image (i.e., a pointer to a pixrect). Button, choice, toggle, and text 
items also have a menu component. Thus the user may interact with most items 
in either of two ways: by selecting the item directly or by selecting from the 
item’s menu. 

Each item type is introduced briefly below. 

Message Items The only visible component of a message item is a label, which may be an image 

or a string in a specified font. Message items are useful for annotations of all 
kinds, including titles, comments, descriptions, pictures, and dynamic status mes- 
sages. 

Message items are selectable, and you may specify a notify procedure to be 
called when the item is selected. 

Button items allow the user of a program to initiate commands. Buttons, like 
message items, have a label, are selectable, and have a notify procedure. Button 
items differ from message items in that they have visible feedback for preview- 
ing and accepting the selection. 

Choice items allow the user to select one choice from a list. The displayed form 
of a choice item can vary radically, depending on how you set its attributes. A 
choice item can be presented as: 

□ a horizontal or vertical list of choices, with all choices visible and the current 
choice indicated by a mark (such as a checkmark); 

□ a horizontal or vertical list of choices, with all choices visible and the current 
choice in reverse-video; 

□ a “cycle item", or list of choices with only the current choice visible. Select- 
ing the item causes the next choice in the list to be selected and displayed; 

□ a dial, knob or switch with a pointer of some sort which turns to indicate one 
of several choices; 

□ a place holder for a pop-up menu, with only the label visible until the menu 
button is pressed. 

Asun 
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Toggle Items 



Text Items 



Slider Items 



Behind this flexibility of presentation lies a uniform structure consisting of a 
label, a list of choices, and, optionally, a corresponding lists of on-marks and 
off-marks used to indicate which choice is currently selected. 

In appearance and structure, toggle items are identical to choice items. The 
difference lies in the behavior of the two types of items when selected. In a 
choice item exactly one element of the list is selected, or current , at a time. A 
toggle item, on the other hand, is best understood as a list of elements which 
behave as toggles: each choice may be either on or off, independently of the 
other choices. Selecting a choice causes it to change state. There is no concept 
of a single current choice; at any given time all, some, or none of the choices 
may be selected. 

Text items are basically type-in fields with optional labels and menus. You can 
specify that your notify procedure be called on each character typed in, only on 
specified characters, or not at all. This allows an application such as a forms- 
entry program to process input on a per character, per field, or per screen basis. 

Slider items allow the graphical representation and selection of a value within a 
range. They are appropriate for situations where it is desired to make fine adjust- 
ments over a continuous range of values. A familiar model would be a horizontal 
volume control lever on a stereo panel. 



9.2. Basic Panel Routines This section covers basic panel usage, including creating and sizing panels, creat- 
ing and positioning panel items, modifying and retrieving the attributes for 
panels and panel items, and destroying panel items. 

Creating and Sizing Panels Like all windows in SunView, panels are created by calling the window creation 

routine with the appropriate type parameter: 





Panel panel; 

panel = window_create ( frame, PANEL, 0); 


\ 






J 



The above call will produce a panel which extends to the bottom and right edges 
of the frame. You can specify the panel’s dimensions explicitly in character 
units via WIN_COLUMNS and WIN_ROWS, or in pixel units via WIN_WIDTH 
and WIN_HEIGHT. 50 

Often you want the panel to be just high enough to encompass all of the items 
within it. After creating all of the items, and before creating any other subwin- 
dows in the frame, set the height of the panel by calling the macro 
window f it_height ( ) . This macro will compute the lowest point occu- 
pied by any of the panel’s items and set the panel height to that point plus a bot- 
tom margin of four pixels. The macros window f it width ( ) to set the 
width, and window f it ( ) to set both the height and the width, are also pro- 
vided. 



50 For a fuller discussion of subwindow sizing and layout see are in Chapter 4, Using Windows. 
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To create a panel item, call: 

Panel_item 

panel__create_item( panel, item_type, attributes) 

Panel panel; 

< item type > i tem_ty pe ; 

<attribute-list> attributes; 

Values for item_type must be one of PANEL_MESSAGE, PANEL_BUTTON, 
PANEL_CHOICE, PANEL_CYCLE, PANEL_TOGGLE, PANEL_TEXT, or 
PANEL_SLIDER. 

Explicit Item Positioning The position of items within the panel may be specified explicitly by means of 

the attributes panel_item_x and panel_item_y. 51 panel_item_x sets 
the left edge of the item’s rectangle (the rectangle which encloses the item’s label 
and value). PANEL_ITEM_Y sets the top edge of the item’s rectangle. 

All coordinate specification attributes interpret their values in pixel units. For 
simple panels and forms which do not make heavy use of images and have only 
one text font, it is usually more convenient to specify positions in character units 
— columns and rows rather than x’s and y’s. You can specify positions in char- 
acter units with the ATTR_ROW ( ) and ATTR_COL ( ) macros, 52 which interpret 
their arguments as rows or columns, respectively, and convert the value to the 
corresponding number of pixels, based on the panel's font, as specified by 
WIN_F0NT. Compare the two calls below: 




The first will place the item at pixel location (10,20), while the second will place 
the item at row 20, column 10. 

NOTE The value computed for attrrow ( ) includes the top margin, given by 

WIN_T0P_MARGIN, and the value computed for ATTR_COL( ) includes the 

left margin, given by WIN_LEFT_MARGIN. The alternate macros 

ATTR ROWS ( ) and ATTR_COLS ( ) are also provided, which compute values 

51 Many attributes, such as those relating to item positioning, apply across all of the item types; these are 
called generic attributes. A comprehensive summary of these generic attributes is given in the Generic Item 
Attributes table in are in Chapter 19, SunView Interface Summary. 

52 ATTR_ROW ( ) and ATTR COL ( ) are described fully in Chapter 18, Attribute Utilities. 
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that do not include the margins. 

Default Item Positioning If you create an item without specifying its position, it is placed just to the right 

of the item on the “lowest row” of the panel, where lowest row is defined as the 
maximum y-coordinate ( PANEL ITEM Y ) of all the items. So in the absence 
of specific instructions, items will be placed within the panel in reading order as 
they are created: beginning four pixels in from the left and four pixels down 
from the top, items are located from left to right, top to bottom. If an item will 
not fit on a row, and more of the item would be visible on the next row, it will be 
placed on the next row. The number of pixels left blank between items on a row 
may be specified by PANEL_ITEM_X_GAP, which has a default value of 10. 
The number of pixels left blank between rows of items may be specified by 
PANEL_ITEM_Y_GAP, which has a default value of 5. 

The default position for the next item is computed after an item is created. But if 
a client calls panel_set ( ) after creating an item in such a way that the 
enclosing rectangle of the item is altered, the default position for the next item 

will not be recomputed. So, for example, 


item = panel_create_item (panel , PANEL_MESSAGE, 0); 
panel_set (item, PANEL_LABEL_STRI NG , "Hi", 0); 

iteml = panel_create_item(panel , PANEL_MESSAGE, 

PANEL_LABEL_STRING, "There", 

0 ) ; 

V / 



will result in There overlapping Hi. 

CAUTION Choice items currently have problems with item “creep.” Each time the label 
of a choice item is set, the position of the item will be evaluated. If the value’s 
position has not been fixed (with VALUE_X/Y), the value is positioned after the 
label. The problem is that the label is baseline-adjusted for a choice item. If the 
item position is not given when the label is set, the choice item will creep down 
because of the baseline adjustment. 

You may also specify the layout of the various components within an item, by 
means of the attributes PANEL_LABEL_X, PANEL_LABEL_Y, 
PANEL_VALUE_X, PANEL VALUE Y, etc. If the components are not expli- 
citly positioned, then the value is placed either eight pixels to the right of the 
label, if PANEL_LAYOUT is PANEL_HORIZONTAL (the default), or four pixels 
below the label, if PANEL_LAYOUT is PAN E L_ V E RT I CAL . 

Modifying Attributes This section describes how to modify the values of attributes of panels or indivi- 

dual panel items which have already been created. 

Since panels are a type of window, their attributes are set with window set ( ) . 
To set attributes of panel items, use: 



Laying Out Components Within 
an Item 
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panel_set ( item, attributes) 

Panel_item item; 

<attribute-list> attributes; 

A macro is provided to ease the syntax for the common operation of setting an 
item's value (attribute PANE L_ VALUE ): 

panel_set_value( item, value) 

Panel_item item; 
caddr_t value; 

Several examples of setting attributes are given here; for a complete list of the 
attributes applying to panels and items, see the tables in are in Chapter 19, Sun- 
View Interface Summary. 



To move a panel's caret to the text item name_item: 





window set (panel, 


\ 




PANEL_CARET_ITEM, 






name_itera, 0); 








y 



To set the value of the choice item f ormat_item to the third choice (choices 
are zero-based): 

Panel_item format_item; 
panel_set_value ( f ormat_item, 2); 

v J 



The first call below creates a message which is initially “hidden” (not displayed 

on the screen); the second call displays the message: 


warning = panel_create_item ( panel , PANELMESSAGE , 

PANEL_LABEL_STRING, "Warning: file will be deleted.", 

P ANEL_SHOW_I TEM , FALSE, 

0 ); 



panel_set (warning, PANEL_SHOW_ITEM, TRUE, 0) ; 
v 



NOTE The values for string-valued attributes are dynamically allocated when they are 
set (at creation time or later). If a previous value was present, it is freed after the 
new string is allocated. This is in contrast to the storage-allocation policy for 
retrieving attributes, described in the section titled Retrieving Attributes . 
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Panel-Wide Item Attributes Some attributes which apply to items may be set for all items in the panel by set- 

ting them when the panel is created. Such attributes include whether items have 
menus, whether item labels appear in bold, whether items are laid out vertically 
or horizontally, and whether items are automatically repainted when their attri- 
butes are modified . 53 For example, the call: 



7 


panel = window create ( frame, PANEL 




■\ 




PANEL SHOW MENU, 


FALSE, 






PANEL LABEL BOLD, 


TRUE, 






PANEL LAYOUT, 


PANEL_VERT ICAL , 






PANEL PAINT, 


PANEL_NONE , 






0); 












/ 



overrides the defaults for all the attributes mentioned: any items subsequently 
created in that panel will not have menus, will have their labels printed in bold 
and their components laid out vertically, and will not be repainted automatically 
when their attributes are modified. 

NOTE When you set the attribute panel_layout, it will only affect the components 
in each item, not the items themselves. That is, all items in a panel will not be 
layed out vertically. 

Keep in mind that he panel-wide item attributes mentioned above are only used 
to supply default values for items which are subsequently created. This means, 
for example, that you cannot change all the item labels to bold by first creating 
the items and then setting PAN E L_L AB E L_BOLD to true for the panel. 

Retrieving Attributes Use window_get ( ) to retrieve attributes for a panel. To retrieve attributes 

applying to panel items, use: 

caddr_t 

panel_get( item, attribute[, optional_arg] ) 

Panel_item item; 

Panel_attribute attribute; 

Panel_attribute optional_arg; 

A macro is provided to ease the syntax for the common operation of getting an 
item's value (attribute PANEL_VALUE ): 

caddr_t 

panel_get_value ( item, value ) 

Panel_item item; 
caddr_t value; 

Since the *_get ( ) routines are used to retrieve attributes of all types, you 
should coerce the value returned into the type appropriate to the attribute being 
retrieved, as in the examples below. 



53 For a complete list of panel- wide item attributes, see the Panel Attributes table in are in Chapter 19, 
SunView Interface Summary. 
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Destroying Panel Items 



To find out whether an item is currently being displayed on the screen: 


int displayed; 

displayed = ( int )panel_get ( item , PANEL_SHOW_ITEM) ; 
t 



To find out whether the caret in a panel is blinking or non-blinking: 



int blinking; 

blinking = ( int )window_get (panel , PANEL BLINK CARET) ; 
v / 



To get the image for a choice item's third (counting from zero) choice: 
. 

Pixrect *image; 

image = (Pixrect * ) panel_get ( item , PANEL_CHOICE IMAGE, 2); 

v ) 



The above example illustrates the use of the optional arg argument, which 
is used for only a few item attributes. 

NOTE panel_get ( ) does not dynamically allocate storage for the values it returns. 

If the value returned is a pointer, it points directly into the panel's private data. It 
is your responsibility to copy the information pointed to. The policy for setting 
attributes is different: the values for string-valued attributes are dynamically 
allocated (see the note above under Modifying Attributes ). 

To destroy a panel item (and free its associated dynamic storage), call: 

panel_destroy_item( item) ; 

Panel_item item; 
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9.3. Using Scrollbars With 
Panels 

Creating Scrollbars 



Scrolling Panels Which 
Change Size 



A scrollable panel is a large panel which can be viewed through a smaller 
subwindow by means of scrollbars. 



Scrollbars come in two orientations: vertical and horizontal. The call below 
creates a panel with both vertical and horizontal scrollbars (as would be desirable 
in a long, many-columned table, for example): 





panel = window_create( frame, PANEL, 




■\ 




WIN_VERTICAL SCROLLBAR, 


scrollbar create(O), 






WIN HORIZONTAL SCROLLBAR, 


scrollbar create(O), 






0); 












J 



The values of the attributes WIN_VERTICAL_SCR0LLBAR and 
WIN_H0RIZ0NTAL_SCR0LLBAR are the scrollbars which are returned by the 
scrollbar_create( ) calls . 54 

Commonly the scrollbar will remain attached to the panel for the duration of the 
panel's existence, and there will be no need to modify the scrollbar’s attributes. 
In this simple case, there is no need to save the handle returned by 
scrollbar_create ( ) . If you desire to destroy the scrollbar, modify its 
attributes, or detach it from one panel and attach it to another, you must either 
save the handle or retrieve it from the panel . 55 For example, to destroy a panel’s 
vertical scrollbar: 



scrollbar_destroy (panel_get (panel, WIN_VERTICAL_SCROLLBAR ) ) ; 
panel_set (panel, WIN_VERTICAL_SCROLLBAR, NULL, 0); 

l 



Often panels are used to display information for browsing, iconedit(l), for 
example, uses a popup panel to allow the user to browse through the images in a 
directory. The easiest way to do this is to create the panel items anew each time 
different information is displayed. For example, the iconedit function which 
fills the browsing panel first destroys any existing panel items, then creates an 
item for each image found. 

If you are going to change the size of the panel in this way, you must inform the 
scrollbar of the new size by calling the function: 

panelupda tescrollings i ze ( panel ) 

Panel panel; 



54 The call scrollbar create ( 0 ) produces a default scrollbar. It is usually best to create a default 
scrollbar and let the user specify how it looks via defaultsedit. You can, of course, override the user’s default 
settings by explicitly setting the scrollbar’s attributes. For a complete list of scrollbar attributes see Chapter 19, 
SunView Interface Summary. 

55 In order to save the scrollbar’s handle or reference any scrollbar attributes you must include the file 

<suntool/scrollbar . h>. 
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Detaching Scrollbars from 
Panels 



The correct time to call panel_update_scrolling_size ( ) is after you 
have created all the items and given them labels. If you don’t update the 
scrollbar’s idea of the panel's size, the size of the scrollbar’s bubble will be 
wrong. 

You may want the same panel to be scrollable at one time, and not scrollable at 
another. The code fragment below illustrates how this can be accomplished by 

attaching and detaching a scrollbar from a panel: 


panel = window_create ( frame, PANEL, 0); 

(create items , do any other processing...) 

/* create scrollbar and attach it to panel */ 
sb = scrollbar_create ( 0 ) ; 

panel_set (panel , WIN_VERTICAL_SCROLLBAR, sb, 0); 

( panel functions with scrollbar...) 

/* now detach scrollbar from panel */ 

panel_set (panel, WIN_VERTICAL_SCROLLBAR, NULL, 0); 

(panel functions without scrollbar...) 

scrollbar_destroy (sb) ; 

v. ) 



Note that the two packages are to be considered from the application’s viewpoint 
as independent packages which can be used together. The application, not the 
panel package, has the responsibility for creating any scrollbars. In order to free 
the application of the responsibility for destroying the scrollbar, panels, when 
they are destroyed, destroy any scrollbars attached to them. However, detaching 
a scrollbar from a panel, as in the above example, does not cause that scrollbar to 
be destroyed. The same scrollbar may be attached and detached from any 
number of panels any number of times. 

The sections which follow discuss the six item types in detail. 
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9.4. Messages 
Example 



9.5. Buttons 
Button Selection 

Button Notification 



Messages are the simplest of the item types. Their only visible component is 
their label. They have no value or menu. 

Message items, like buttons, are selectable and can have notify procedures. The 
selection behavior of messages differs from that of buttons in that no feedback is 
given to the user when a message is selected. 

In the following example, two message items are used together to give a warning 
message: 




You may change the label for a message item (as for any type of item) via 
PANEL_LABEL_STRING or PANEL_LABEL_IMAGE. 

Button items have a label and a menu, but no value. 

When the left mouse button is pressed over a button item, the item’s rectangle is 
inverted. When the mouse button is released over a button item, the item’s rec- 
tangle is painted with a grey background, indicating that the item has been 
selected and the command is being executed. The grey background is cleared 
upon return from the notify procedure. 

The procedure specified via the attribute PANEL_NOTlFY_PROC will be called 
when the item is selected. The form of the notify procedure for a button is: 

button_notify_proc( item, event) 

Panel__item item; 

Event * event; 
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Button Image Creation Utility 



Examples 



A routine is provided to create a standardized, button-like image from a string: 
Pixrect * 

panel_button_image( panel, string, width, font) 

Panel panel; 

char * string; 
int width; 

Pixfont *font; 

where width indicates the width of the button, in character units. The value 
returned is a pointer to a pixrect showing the string with a border drawn around 
it. If width is greater than the length of string, the string will be centered in 
the wider border; otherwise the border will be just wide enough to contain the 
entire string (i.e., the string will not be clipped). The font is given by font — if 
NULL, the font for panel is used. 

A button image is a separate object, and therefore is not destroyed with the but- 
ton, It may be reused, for example, with another button. Thus, the memory allo- 
cated by panel_button_image ( ) for the panel button image is not freed 
when the panel button is destroyed. This can result in the loss of useable memory 
(“ memory leakage”), which is cumulative and eventually causes the system to 
crash. 

To avoid this leak, create the button image explicitly, so that it has a handle by 
which it can be destroyed. The color panel example programs in UpdateSwn- 
Vfewl.80 show how this is done. 



The first example renders the string in the default system font, found in 
/usr/lib/f onts/f ixedwidthf onts/screen . r . 13: 



(Reset J 



f V 

panel_create_item(panel , PANEL_BUTTON , 

PANEL_NOTIFY_PROC, quit_proc, 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "Reset", 0, 0), 
0 ); 

t 



The button below has a bold font and a seven character wide border: 

[ Reset 1 





bold = pf_open ( "/usr/lib/fonts/f ixedwidthf onts/screen .b. 12" ) ; 
panel_create_i tem ( panel , PANEL_BUTTON , 

PANEL_NOTIFY_PROC, quit_proc, 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "Reset" , 7, bold) , 
0 ); 

l / 



It is often useful to associate a menu with a button. Figure 9-1 illustrates a but- 
ton representing an online manual. The menu over the button allows the user to 
bring up the text for the different chapters: 



wsun 

Xr microsystems 



Revision A, of March 27, 1990 







156 SunView Programmer’s Guide 



Figure 9-1 



Associating a Menu With a Button 
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To do this, you must write your own event procedure, as described in Section 
9.1 3, Event Handling. On receiving a right mouse button down event, display 
the menu and take the appropriate action depending on which menu item the user 
selects. For all other events, call the panel’s default event procedure. 



Here is the code to create the menu and the button, and the event procedure to 
display the menu: 



static short book_array[] = { 

#include "book . image" 

1 ; 

mpr_static(book, 64, 64, 1, book_array) ; 



Menu menu = menu create ( MENU NCOLS, 3, MENU STRINGS 



" Introduction" , 
"SunView Model", 
"Windows" , 
"Canvases " , 
"Input" , 

0 ); 



" Pixwins " , 

"Text Subwindows", 
" Panels " , 

"TTY Subwindows", 
"Menus " , 



" Cursors " , 

" Icons " , 

" Scrollbars " , 
"Selection Service", 
"Notifier", 0, 



panel_create_item{panel , PANEL_BUTTON, 

PANEL_LABEL_ IMAGE , Shook , 
PANEL_EVENT_PROC , handle_panel_event , 
0 ); 



handle_panel_event ( i tem , event) 

Panel_item item; 

Event * event; 

{ 

if (event_act ion (event ) == 

MS_RIGHT && event_is_down (event ) ) { 

int chapter = menu_show(book_menu, panel, event, 0); 
switch (chapter) { 

case 1: /* Introduction */ break; 
case 2: /* Pixwins */ break; 



case 15: /* Notifier */ break; 

} 

] else 

panel_def ault_handle_event ( item, event ) ; 
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9.6. Choices 



Displaying Choice Items 



Choice items are the most flexible — and complex — item types . 56 Besides the 
label, they are composed of: 

□ a list of either image or string choices (specified via the attributes 

PANEL_CHOICE_IMAGES or PANEL_CHOICE_STRINGS ). 

□ a list of mark-images — images to be displayed when the corresponding 
choice is selected ( PAN EL_MARK_ images ). The default mark is a push- 
button with the center inverted. 

□ a list of nomark-images — images to be displayed when the corresponding 
choice is not selected ( PANEL_NOMARK_ images ). The default nomark 
image is a non-inverted push-button. 

The choices are numbered beginning with zero, and there is no restriction on the 
number of choices a single choice item may have. 

The attribute PANEL_DISPLAY_LEVEL determines which of an item's choices 
are actually displayed on the screen. The display level may be set to: 

□ PANEL_ALL, (the default) all choices are shown; 

□ PANEL_CURRENT, only the current choice is shown; 

□ PANEL_NONE, no choices are shown. Since the only way of selecting a 
choice is through the menu, this becomes a label with an associated pop up 
menu. 

If the display level is PANEL_CURRENT or PANEL_ALL, the choices are placed 
by default horizontally after the label. You can lay them out vertically below the 
label by setting panel_layout to panel_vertical. If you want to place 
the choices or marks more precisely — in order to model a switch or some other 
special form — you can do so by setting the appropriate attribute, such as 
PANEL_CHOICE_XS, PANEL_CHOICE_YS, PANEL_MARK_XS, 
panel_mark_ys, etc. 

A few words about using the various lists in choice items. The list you give for 
PANEL_CH0ICE_STRINGS (or PANEL_CH0ICE_IMAGES ) determines the 
item's choices . 57 

The parallel lists PANEL_CHOICE_FONTS, PANEL_MARK_IMAGES, 
PANEL_NOMARK_IMAGES, PANEL_MARK_XS, PANEL_MARK_Y S , 
PANEL_CHOICE_XS, and PANEL_CHOlCE_YS are interpreted with respect to 
the list of choices. For example, the first font given for 
PANEL_CHOICE_FONTS will be used to print the first string given for 
PANEL_CH0ICE_STRINGS, the second font will be used for the second string, 



56 For a complete list of the attributes applicable to choice items, see the Choice Item Attributes table are in 
Chapter 19, SunView Interface Summary. 

57 You must specify at least one choice, so the least you can specify is a single choice consisting of the null 
string. 
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and so on. 

The item below, taken from i coned it, shows how parallel lists can be abbrevi- 
ated: 



□ 




T 



H 



panel create_i tern ( iced_panel , 
PANEL_MARK_IMAGES , 
PANEL_NOMARK_IMAGES , 

PANEL CHOICE IMAGES, 



PANEL_VALUE , 
PANEL_CHOICE_XS , 
PANEL_MARK_XS , 
PANEL_CHOICE_YS , 
PANEL_MARK_YS , 
PANEL_NOTIFY_PROC , 
0 ); 



— 

PANEL_CHOICE , 

&down_triangle, 0, 

0 , 

&square_white, &square_25, 
&square_root , &square_50, 
&square_75, &square_black , 0, 
2 , 

30, 60, 90, 120, 150, 180, 0, 

34, 64, 94, 124, 154, 184, 0, 
345, 0, 

363, 0, 

proof_background_proc , 



Choice Selection 



The item has six choices, representing the six available background patterns for 
the proof area. Note, however, that three of the lists, — 

PAN EL_MARK_ IMAGES, PANEL_CHOICE_YS and PANEL_MARK_Y S all 
have only one element. When any of the parallel lists are abbreviated in this 
way, the last element given will be used for the remainder of the choices. So, the 
345, 0 in the example above serves as shorthand for 345, 345, 345, 

345, 345, 345, 0. All the choice images will appear at y coordinate 34 5, 
all the mark images will appear at y coordinate 363, and all the choices will have 
down_triangle as their mark image. 

NOTE You can’t specify that a choice or mark-image appear atx-Oory-Oby using 
the attributes PANEL_CHOICE_XS, PANEL_CHOICE_YS , 
PANEL_MARK_XS or PANEL_MARK_YS. Since these attributes take null- 
terminated lists as values, the zero would be interpreted as the terminator for the 
list. You may achieve the desired effect by setting the positions individually, 
with the attributes PANEL_CHOICE_X, PANEL_CHOICE_Y, 

P ANEL_MARK_X , or PANEL MARK Y, which take as values the number of the 
choice or mark, followed by the desired position. 



The user can make a selection from a choice item either by selecting the desired 
choice directly, by selecting from the associated menu, or by selecting the label, 
which causes the current choice to advance to the next choice (or backup to the 
previous choice if the shift key is pressed while selecting). 

Feedback for choice items comes in two flavors — inverted, in which the current 
choice is shown in reverse video, and marked, in which the current choice is indi- 
cated by the presence of a distinguishing mark, such as a check-mark or arrow. 
Specified the type of feedback you want by setting PANEL_FEEDBACK to either 
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Choice Notification 



Choice Value 



Choice Menus 



Examples 



PANEL_INVERTED or PANEL_MARKED. 

You may also disable feedback entirely, by setting PANEL_FEEDBACK to 
PANEL_NONE. 

The default feedback is PANEL_MARKED, unless the item's display level is 
current, in which case the feedback is PANEL NONE. 

The procedure specified via the attribute PANEL_NOTIFY_PROC will be called 
when the item is selected. Choice notify procedures are passed the item, the 
current value of the item, and the event which caused notification: 

choice_notify_proc( item, value, event) 

Panel_item item; 
int value; 

Event * event; 



The value passed to the notify procedure is the ordinal number corresponding to 
the current choice (the choice which the user has just selected). The first choice 
has ordinal number zero. 

Choice and Toggle items are the only item types for which a menu appears by 
default. To disable the menu for a particular item, set PANEL_SHOW_MENU for 
that item to false. 

Choice item menus may be used to represent either a simple menu or a checklist. 
The former is a menu of commands, which gives no indication of which com- 
mand was executed last; the latter is a menu of choices with a check-mark indi- 
cating the current choice. Set PANEL_SHOW_MENU_MARK to FALSE to obtain 
a simple menu, or TRUE to get a checklist. 

NOTE The number of menu choices, if set by PANEL_MENU_CHOICE_STRlNGS or 
PANEL_MENU_CH0ICE_IMAGES, must be equal to the number of choices for 
the item. 



As a basis for our examples we’ll take the item in iconedit which allows the 
user to select the drawing mode. The item could have been presented in several 
different forms. 

The simplest call would specify the label and choices as strings, and take the 
defaults for all other attributes. All the choices will be displayed, and the feed- 
back will be marked, with push-buttons for the mark images: 



Drawing Mode: 0 Points 9 Line 0 Rectangle 0 Circle 0 Text 



panel_create_item (panel, 
PANEL_LABEL_STRING, 
PANEL CHOICE STRINGS 



0); 



PANEL_CHOICE, 
"Drawing Mode:", 
"Points", "Line", 
"Circle", "Text", 



"Rectangle” , 

0 , 
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You can specify a custom mark, such as this small pointer, to indicate the current 
choice: 



Drawing Mode: Points ►Line Rectangle Circle Text 



static short pointer array [ ] = { 

^include "pointer. pr" 

1 ; 

mprstatic (pointer , 16, 16, 1, pointer_array ) ; 



panel_create_item ( panel , PANEL_CHOICE , 

PANEL_LABEL_STRI NG , "Drawing Mode:", 

PANEL_MARK_IMAGES , &pointer, 0, 
PANEL_NOMARK_IMAGES , 0, 

PANEL_CHOICE_STRINGS , "Points", "Line", "Rectangle", 

"Circle", "Text", 0, 

0 ); 



Setting PANEL_FEEDBACK to PANEL_INVERTED produces: 

Drawing Mode: Points [QQ Rectangle Circle Text 
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Often space on the panel is limited, and it is appropriate to save space by only 
showing the currently selected choice. You can do that by disabling feedback 
and displaying only the current choice: 

Drauing Mode: Line 





panel_create_item (panel , PANELCHOICE , 

PANEL_LABEL_STRING, "Drawing Mode:", 

PANEL_CHOICE_STRINGS , "Points", "Line", "Rectangle", 

"Circle", "Text", 0, 
PANEL_DISPLAY_LEVEL , PANEL_CURRENT , 

PANEL_FEEDBACK, PANEL_NONE , 

0 ); 

s. ' 



Such an item has the drawback of looking to the user like a text item. One solu- 
tion to this problem is to provide a distinguishing mark which clearly indicates 
the item’s type, as in: 

Drauing Mode: CLine 



The double-arrow image suggests a cycling motion, indicating to the user that the 
item is a choice item with more choices available. To get the cycle image, use 
the special item type PANEL_CYCLE: 58 



panel_create_item (panel , PANEL_CYCLE , 

PANEL_LABEL_STR I NG , "Drawing Mode:", 

PANEL_CHOICE_STRINGS, "Points", "Line", 

"Circle", "Text", 



0 ) ; 



"Rectangle" , 
0 , 



58 Note that a cycle item is simply a choice item with some attributes initialized — the display level is set to 
current and the on-mark is set to the cycle image. Once created, cycle items behave in exactly the same way as 
choice items. 
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With some effort, you can use a choice item to model a dial, as in Figure 9-2. 
Figure 9-2 A Dial-Like Choice Item 

Rect 

Line ^ — - Circle 
Points [ \ Text 

Drawing Mode 

The way to make a such a dial is to make an image for each dial setting, and use 
these images as the on-marks. Place the on-marks and the choices explicitly — 
the on-marks in the center, forming the dial, and the choices around the dial’s 
perimeter: 







\ 




panel create item(panel. 


PANEL_CHOICE , 




PANEL_CHOICE_ST RINGS 


"Points", "Line", "Rect", 
"Circle", "Text", 0, 




PANEL_MARK_IMAGES , 


&dial_l, &dial_2, &dial_3, 
&dial 4, &dial 5, 0, 




PANEL NOMARK IMAGES, 


0, 




PANEL_CHOICE_XS, 


7, 34, 82, 133, 145, 0, 




PANEL CHOICE YS, 


53, 33, 20, 33, 53, 0, 




P ANEL_MARK_XS , 


66, 0, 




PANEL_MARK_YS, 


O 

o 




PANEL_LABEL_STRING, 


"Drawing Mode", 




PANEL LABEL X, 


30, 




PANEL_LABEL_Y, 
PANEL LABEL FONT, 


65, 




pf_open ( "/usr/lib/fonts/f ixedwidthfonts/gallant . r . 19" ) , 
0); 


V, 




J 



The form which is actually used in i coned it is shown in Figure 9-3. It 
employs vertical layout, images for the choices, and strings for the menu: 



Figure 9-3 iconedit’j Drawing Mode Choice Item 
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9.7. Toggles 



Displaying Toggles 



Toggle Selection 



Toggle Notification 



Toggle Value 



Example 





panel create itein(panel, PANEL 


CHOICE, 


> 




PANEL LAYOUT, 


PANEL_VERTICAL, 






PANEL_CHOICE_IMAGES , 


&points, &line, 


&rectangle. 






&circle, &text, 


0, 




PANEL_MENU_CHOICE STRINGS, 


"Points", "Line 


", "Rectangle", 






"Circle", "Text 


", o, 




PANEL_MARK_I MAGES, 


&drawing_hand , 


o, 




PANEL NOMARK_IMAGES , 


0, 






0); 






l, 






J 



Toggle items are identical in structure to choice items — they have a label and 
parallel lists of choices, on-marks and off-marks. They differ from choice items 
in certain aspects of their display options, their selection behavior and the 
interpretation of their value. These differences are highlighted below. 

Toggle items may have a PANEL_DISPLAY_LEVEL of either PANEL_ALL — 
all choices visible, or PANEL_NONE — no choices visible. The default is 
PANEL_ALL. 

Since there is no notion of the current choice for a toggle item, a display level of 
PANEL_CURRENT is not allowed. 

Toggle items, like choice items, may have either inverted or marked feedback, 
depending on the value of PANEL_FEEDBACK. The default is 
PANEL_MARKED. For inverted feedback, specify PANEL_INVERTED. 
panel_none is not allowed. 

Toggle items may be selected by clicking on the desired choice or through the 
menu. Selecting a choice causes that choice to toggle on or off (change state); 
other choices are not affected. 

If there is only one choice, it may be toggled by selecting the label; if there is 
more than one choice, selecting the label has no effect. 

The parameters for the notify procedure are the same as for choice items except 
that the value passed is a bit mask instead of an integer: 

toggle_notify_proc( item, value, event) 

Panel_item item; 

unsigned int value; 

Event * event; 



The value passed to the notify procedure is a bit mask representing the state of 
the first 32 choices — if a bit is one, then the corresponding choice is on, if a bit 
is zero, then the corresponding choice is off. (The least significant bit is bit zero, 
which maps to choice zero.) 

Figure 9-4 illustrates an item which lets you set the -l, -r, or -a flags for the Is 
command: 
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Figure 9-4 A Toggle Item 



Format Options: 
Ef Long 
□ Reverse 
ST Show all fi les 



forma titem = panel_create_item (panel , PANEL_TOGGLE, 
PANELLABELSTRING, "Format Options:", 
PANEL_LAYOUT , PANELVERTICAL , 

PANEL_CHOICE_STRINGS , "Long", 

" Reverse" , 

"Show all files", 

0 , 

PANEL_TOGGLE_VALUE, 0, TRUE, 

PANEL_TOGGLE_VALUE , 2, TRUE, 

PANEL_NOTIFY_PROC, forma t_not if y_proc, 

0 ); 



You can get or set the value of a particular choice — including choices beyond 
the first 32 — with PANEL_TOGGLE_VALUE. When used to set the value, this 
attribute takes two values: the index of the choice to set, and the desired value. 

In the above example, PANEL_TOGGLE_VALUE is used to initialize the first and 

third choices to TRUE. To find out the value of the third choice, you would call: 


value = (int) panel get ( format_item , PANEL_TOGGLE_VALUE , 2); 

^ 



You can also use the attribute PANEL VALUE to set and get the state of a 
toggle’s choices. As mentioned on the previous page, a toggle’s value is a bit 
mask representing the state of the first 32 choices. To facilitate working with the 
value, you might first define names corresponding to each choices, and a macro 
to test for the corresponding bit in the value, like this: 





#def ine 


LONG 


0 






#def ine 


REVERSE 


1 






#def ine 


SHOW_ALL 


2 






#def ine 


toggle bit 


_on(value, bit) 


((value) & (1 << (bit))) 










2 



You can then use the value in the notify procedure, as in: 
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Or you can retrieve the value outside of the notify procedure, as in: 




Toggle Menus The menu has as many lines as choices, and each line toggles when selected. In 

other words, the mark indicating “on” (PANEL_MENU_MARK_IMAGE) is alter- 
nated with the mark signifying “off’ (PANEL_MENU_NOMARK_lMAGE) each 
time the user selects a given line. 

To disable the menu, set PANEL_SHOW_MENU to FALSE. 

PANEL_CHOICE_FONT The following example shows the use of the PANEL__CH0ICE_F0NT attribute 

in manipulating the font of a panel choice. 
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9.8. Text 

Displaying Text Items 



frame = window_create(NULL, FRAME, 0); 
panel = window_create( frame, PANEL, 0); 

cour_b_10 = pf_open( 

"/usr/lib/fonts/fixedwidthfonts/cour.b.10" ) ; 
cour_b_12 = pf_open( 

"/usr/lib/fonts/f ixedwidthfonts/cour . b.12" ) ; 
cour_b_14 = pf_open( 

"/usr/lib/fonts/f ixedwidthfonts/cour .b . 14 " ) ; 
cour_b_16 = pf_open( 

"/usr/lib/fonts/f ixedwidthfonts/cour . b . 16 " ) ; 
cour_b_18 = pf_open( 

"/usr/lib/fonts/f ixedwidthfonts/cour . b . 18 " ) ; 

panel_create_item 
(panel, PANEL_CHOICE, 

PANEL_LAYOUT , 

PANEL CHOICE_STRINGS , 



PANEL_CHOICE_FONT , 

PANEL_CHOICE_FONT , 

PANEL_CHOICE_FONT , 

PANEL_CHOICE_FONT , 

PANEL_CHOICE_FONT , 

0 

) ; 

window_f it (panel) ; 
window_fit( frame) ; 
window_main_loop( frame) ; 
exit( 0) ; 

} 

< J 



PANEL_VERTICAL , 

"This is cour.b.10", 
"This is cour.b.12", 
"This is cour.b.14", 
"This is cour.b.16", 
"This is cour.b.18", 
0 , 

0, cour_b_10, 

1, cour_b_12, 

2, cour_b_14, 

3, cour_b_16, 

4, cour_b_18, 



The value component of a text item is the string which the user enters and edits. 
It is drawn on the screen just after the label, as in: 

Name: Eduard G. Robinson 





panel_create_item (panel , PANEL_TEXT , 

PANEL_LABEL_STRING , " Name : " , 

PANEL_VALUE, "Edward G. Robinson", 

0 ); 

\ 



If PANEL_LAYOUT is set to PANEL_VERTICAL, overriding the default of 
P ANE L_HOR I z ONTAL , the value will be placed below the label. 
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Text Selection 



The number of characters of the text item’s value which are display able on the 
screen is set via PANEL_VALUE_DISPLAY_LENGTH, which defaults to 80 
characters. When characters are entered beyond this length, the value string is 
scrolled one character to the left, so that the most recently entered character is 
always visible. As the string scrolls to the left, the leftmost characters move out 
of the visible display area. The presence of these temporarily hidden characters 
is indicated by a small left-pointing triangle. So setting the display length to 12 
in the above call would produce: 

Name: ◄ G . Robinson 

As excess characters are deleted, the string is scrolled back to the right, until the 
actual length becomes equal to the displayed length, and the entire string is visi- 
ble. 

It is sometimes desirable to have a protected field where the user can enter 
confidential information. The attribute PANEL_MASK_CHAR is provided for 
this purpose. When the user enters a character, the character you have specified 
as the value of PANEL_MASK_CHAR will be displayed in place of the character 
the user has typed. So setting PANEL_MASK_CHAR to “ ' * ' ” would produce: 

Passuord: ******** 

If you want to disable character echo entirely, so that the caret does not advance 
and it is impossible to tell how many characters have been entered, use the space 
character as the mask. You can remove the mask and display the actual value 
string at any time by setting the mask to the null character. 

The maximum number of characters which can be typed into a text item 
(independently of how many are displayable) is set via the attribute 
PANEL_VALUE_STORED_LENGTH. Attempting to enter a character beyond 
this limit causes the field to overflow, and the character is lost. The value string 
is blinked to indicate to the user that the text item is not accepting any more char- 
acters. 

The stored length, like the displayed length, defaults to 80 characters. 



A panel may have several text items, exactly one of which is current at any given 
time. The current text item is the one to which keyboard input is directed, and is 
indicated by a caret at the end of the item’s value. (If PANEL_BLINK_CARET 
is TRUE, the caret will blink as long as the cursor is in the panel.) Selection of a 
text item (i.e. pressing and releasing the left mouse button anywhere within the 
item’s rectangle) causes that item to become current. A text item also becomes 
current if it is displayed after being hidden — i.e. if PANEL_SHOW_ITEM is set 
to TRUE. 

You can find out which text item has the caret, or give the caret to a specified text 

item, by means of the panel attribute PANEL_CARET_ITEM. The call 


windowset (panel, PANEL_CARET_ITEM, name_item, 0); 

v / 
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Text Notification 



moves the caret to name_item, while 







N 




( Panel_item)window_get (panel , PANEL_CARET_ITEM) ; 




V... 




/ 



retrieves the item with the caret. 

You can rotate the caret through the text items with the following two routines: 

panel_advance_caret ( panel ) 

Panel panel; 

panel_backup_caret ( panel ) 

Panel panel; 

Advancing past the last text item places the caret at the first text item; backing up 
past the first text item places the caret at the last text item. 

The notification behavior of text items is rather more complex than that of the 
other item types. You can control whether your notify procedure is called on 
each input character or only on selected characters. If your notify procedure is 
called, then the value it returns tells the panel package what to do — whether to 
insert the character, advance to the next text item, etc. 

When your notify procedure will be called is determined by the value of 
PANEL_NOT I F Y_LE VEL. Possible values are given in the following table. 

Table 9- 1 Text Item Notification 



Notification Level 


Causes Notify Procedure to be Called 


PANEL_NONE 


Never 


PANEL_NON_PRINTABLE 


On each non-printable input character 


PANEL_SPECIFIED 


If the input char is found in the string 




given for the attribute 




PANEL_NOT I F Y STRING 


PANEL_ALL 


On each input character 



PANEL_NOT I F Y_LE VEL defaults to PANEL_S PEC I F I ED , and 

PANEL NOTIFY STRING defaults to \n\r\t (i.e., notification on line-feed, 

carriage-return and tab). 

What happens when the user types a character? The panel package treats some 
characters specially. ( Meta-C l , 59 f Meta-W 1 , and [ Meta-X ) are mapped to the Sun- 
View functions ( Copy ) . [ Paste 1 . and ( Cut l respectively. When the user types 
these characters, the panel package notices them and performs the appropriate 
operation, without passing them on to your notify procedure. 

The user’s editing characters — erase, erase-word and kill — are also treated 
specially. If you have asked for the character by including it in 



59 The Meta key is [Left] or [ Right ] on the Sun-2 and Sun-3 keyboards. On the type 4 keyboard, the [ Meta 1 
keys are marked with diamonds [♦"] . 
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PANEL_N0TIFY_STRING, the panel package will call your notify procedure. 
After the notify procedure returns, the appropriate editing operation will be 
applied to the value string. (Note: the editing characters are never appended to 
the value string, regardless of the return value of the notify procedure.) 

Characters other than the special characters described above are treated as fol- 
lows. If your notify procedure is not called, then the character, if it is printable, 
is appended to the value string. If it is not printable, it is ignored. If your notify 
procedure is called, what happens to the value string, and whether the caret 
moves to another text item, is determined by the notify procedure’s return value. 
The following table shows the possible return values: 

Table 9-2 Return Values for Text Item Notify Procedures 



Value Returned 


Action Caused 


PANEL_INSERT 


Character is appended to item’s value 


PANEL_NEXT 


Caret moves to next text item 


PANEL_PREVIOUS 


Caret moves to previous text item 


PANEL_NONE 


Ignore the input character 



If a non-printable character is inserted, it is appended to the value string, but 
nothing is shown on the screen. 



If you don’t specify your own notify procedure, the default procedure 
panel_text_notif y ( ) will be called at the appropriate time, as determined 
by the setting of PANEL_NOTIFY_LEVEL. The procedure is shown below: 

Panel_setting 

panel_text_notify( item, event) 

Panel_item item 
Event * event 

This procedure returns a panel setting enumeration which causes: 1) the caret to 
move to the next text item on ( RETURN ) or ( TAB ) ; 2) the caret to move to the 
previous text item on ( SHIFT 1 [ RETURN 1 or [ SHIFT ] [ TAB: ) 3) printable charac- 
ters to be inserted; and 4) all other characters to be discarded. 

By writing your own notify procedure, you can tailor the notification behavior of 
a given text item to support a variety of interface styles. On one extreme, you 
may want to process each character as the user types it in. For a different appli- 
cation you may not care about the characters as they are typed in, and only want 
to look at the value string in response to some other button. A typical example is 
getting the value of a filename field when the user presses the Load button. 

Text item notify procedures are passed the item and the event which caused 
notification: 

Panel_setting 

text_notif y_proc ( item, event) 

Panel_item item; 

Event * event; 



Writing Your Own Notify 
Procedure 
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The input character is referenced by event_action ( event ) . 



For example, suppose you want to be notified only when the user types ( Esc 1 or 
[ Control-C 1 into an item, but you still want them to be able to move to the next 
item, tab, or select 1 RETURN, j Create the item as shown below. 



S' 






A 




nameitem = panel_create_item (panel , PANELTEXT, 






PANEL_LABEL_STRING, 


"Enter Name Here:", 






PANEL_NOT I FY_LEVEL , 


PANEL_SPECIFIED, 






P ANEL_NOT I F Y_STR I NG , 


"\n\r\t\033\003 " , 






PANEL NOTIFY PROC, 


name proc, 






0); 






ly, 






J 



Note that you must remember to return the appropriate value from your notify 
procedure. The easiest way to do this is to simply call the default text notify pro- 
cedure, and return what it returns: 



Panel_setting 
name_proc ( item, event) 

Panel_iteni item; 

Event * event; 

{ 

switch (event_action (event ) ) [ 

case '033': /* user pressed [Esc] */ 

/* special processing of escape *1 
return (PANEL_NONE) ; 

case '003': /* user pressed [Ctrl-C] */ 

/* special processing of~C */ 
return (PANEL_NONE) ; 



} 



default : 
return 



] 



(panel_text_notify ( item, 



event) ) ; 



Text Value As shown in the example under Displaying Text Items, you can set the value of a 

text item at any time via PANEL_VALUE. You can also use the 
panel_set_value( ) macro, as in: 







A 




panel_set_value( name_item, "Millard Fillmore"); 








) 



The following call retrieves the value of name_item into name: 



Panel_item name_item; 

char name [ NAME_ITEM_MAX_LENGTH] ; 

strcpy(name, (char * ) panel_get_value ( name_item) ) ; 

^ ; 



Note that name item should have been created with a 
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Text Menus 
Example 



PANEL_VALUE_STORED_LENGTH not greater than 
NAME_ITEM_MAX_LENGTH, so the buffer name will not overflow. 

A menu may be associated with a text item by setting PANEL_SHOW_MENU to 
TRUE. 

One use of text item menus is to make any item-specific “accelerators”, or char- 
acters which cause special behavior, visible to the user. This usage of accelera- 
tors may be seen in Figure 9-5 which is taken from iconedit. The item 
labelled File: holds the name of the file being edited. In addition to typing print- 
able characters, which are appended to the value of the item, the user can type 
f Esc 1 for filename completion, 1 Control-L 1 to load an image from the file, 

[ Control-S ) to store an image to the file, or ( Control-Bl to browse the images in a 
directory. 

Figure 9-5 A Text Menu 



File: dervish. image 



ESC - Filename completion 



- Load image from file 



*S - Store image to file 
- Browse directory 
A Q - Quit 



#def ine ESC 27 
#def ine CTRL_L 12 
#def ine CTRL_S 19 
#define CTRL_Q 17 
#def ine CTRL B 2 



f ilename_item = panel_create_item (panel , PANEL_TEXT, 



PANEL_LABEL_STRING, 
PANEL_NOTI FY_LEVEL , 
PANEL_NOTI FY_PROC , 
PANEL_VALUE_DISPLAY_LENGTH, 
PANEL_SHOW_MENU , 

PANEL MENU CHOICE STRINGS, 



PANEL_MENU_CHO I CE_ VALUES , 
0 ); 



"File: " , 

PANELALL, 
f ilename_proc, 

18, 

TRUE, 

ESC - Filename completion", 
~L - Load image from file", 
~S - Store image to file", 
~B - Browse Directory", 

~Q - Quit", 

0 , 

ESC , CTRL_L , CTRL_S , 

CTRL B , CTRL Q, 0, 



The last two attributes specify the menu. PANEL_MENU_CHOICE_STRlNGS is 
a null-terminated array of strings to appear as the selectable lines of the menu. 
The value that the menu returns for each of its lines is specified via 
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9.9. Sliders 
Displaying Sliders 



Slider Selection 
Slider Notification 



PANEL_MENU_CH0ICE_VALUES. So if the menu line ‘"L - Load image from 
file’ is selected, the menu will return the value CTRL L. The value returned by 
the menu is passed directly to the text item, just as if it had been typed at the key- 
board. 



A slider has four displayable components: the label, the current value, the slider 
bar, and the minimum and maximum allowable integral values (the range). 

When PANEL_SHOW_ VALUE is TRUE, the current value is shown in brackets 
after the label. The font used to render the value is PANEL VALUE FONT. 

The slider bar width in pixels is set with PANEL_SLIDER_WIDTH. 60 The 
minimum and maximum allowable values are set with PANEL_MIN_VALUE 
and PANEL_MAX_VALUE. The width of the slider bar corresponding to the 
current value is filled with grey. The slider bar is always displayed, unless the 
item is hidden (i.e., PANEL_SHOW_iTEM is FALSE). When 
PANEL_SHOW_RANGE is TRUE, the minimum value of the slider 
(PANEL_MIN_VALUE) is shown to the left of the slider bar and the maximum 
value (PANEL_MAX_VALUE) is shown to the right of the slider bar. 

Only the slider bar of a slider may be selected. When the left mouse button is 
pressed within the slider bar or the mouse is dragged into the slider bar with the 
left mouse button pressed, the grey shaded area of the bar will advance or retreat 
to the position of the cursor. If the mouse is dragged left or right within the 
slider bar, the grey area will be updated appropriately. If the cursor is dragged 
outside of the slider bar, the original value of the slider (i.e., the value before the 
left button was pressed) will be restored. 

Slider notify procedures are passed the item, the item’s value at time of 
notification, and the event which caused notification: 

slider_notify_proc( item, value, event) 

Panel__item item; 
int value; 

Event * event; 

The notification behavior of a slider is controlled by P ANEL_NOT I F Y_L EVEL. 
When PANEL_NOTl FY_LE VEL is set to PANEL_DONE, the notify procedure 
will be called only when the select button is released within the slider bar. When 
PANEL_NOTlFY_LEVEL is set to PANEL ALL, the notify procedure will be 
called whenever the value of the slider is changed. This includes: 

□ when the select button is first pressed within or dragged into the slider bar, 

□ each time the mouse is dragged within the slider bar, 



60 If you want to specify the width in characters, use the “column units” macro ATTR COLS ( ) described in 
Chapter 18 , Attribute Utilities. 
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Slider Value 



Example 



□ when the mouse is dragged outside the slider bar, 

□ when the select button is released. 

The value of a slider is an integer in the range PANEL_MI N_VALUE to 
PANEL MAX VALUE. You can retrieve or set a slider’s value with the attribute 
PANEL_VALUE. 

Figure 9-6 illustrates a typical slider, which might be used to control the bright- 
ness of a screen: 

Figure 9-6 A Typical Slider 



Brightness: [75] 




100 





panel create item ( panel , PANEL_SLIDER 


a 




PANEL_LABEL_STRING , 


"Brightness: ", 




PANEL VALUE, 


75, 




PANEL MIN VALUE, 


o, 




PANEL MAX VALUE, 


100, 




PANEL_SLIDER_WIDTH , 


300, 




PANEL_NOT IFY_PROC , 


brightness_proc. 




0); 








J 



9.10. Painting Panels and 
Individual Items 



To repaint either an individual item or an entire panel, use: 

panel_pa int ( panel_ob ject , pa int_behavior ) 
<Panel_item or Panel> panel_ob j ect. ; 
Panel_setting paint_behavior ; 



paint_behavior should be either PANEL__CLEAR, which causes the rectan- 
gle occupied by the panel or item to be cleared prior to repainting, or 
PANEL NO CLEAR, which causes repainting to be done without any prior clear- 
ing. 

You don’t have to call panel paint ( ) for items which you create at the same 
time as you create the panel — when the panel is initially displayed, each of its 
items will be painted. Note, however, that simply creating a panel item does not 
cause it to be painted. So items which you create after the panel has been ini- 
tially displayed will not appear until you call panel_paint ( ) . 

The special attribute PANEL PAINT is provided to allow you to control the 
“repaint behavior” of an item when one of its attributes is set. PANEL_PAINT 
has three possible values: 

□ PANEL_CLEAR — the item will be automatically cleared and repainted 
after each call to panel_set ( ) . 

□ PANEL_NO_CLEAR — the item will be automatically repainted (without 
any prior clearing) after each panel_set ( ) call. 
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□ PANEL NONE — no automatic repainting will be done. 

The default value for PANEL_PAINT is PANEL_CLEAR. Thus, in the default 
case, you do not need to call panel_paint ( ) after calling panel_set ( ) . 
You can set the repaint behavior for an item when the item is created, or for all 
items in the panel when the panel is created. The item’s repaint behavior may 
not be reset after the item is created. However, you may temporarily override an 
item’s repaint behavior on any call to panel set ( ) by giving a different set- 
ting for PANEL PAINT. The examples which follow show two possible repaint 
policies. 



Example 1: 





iteml = panel_create_item (panel , PANEL_TEXT, 

PANELLABELSTRING, "Enter Name:", 

PANEL_VALUE_DISPLAY_LENGTH, 10, 

PANEL_PAINT , PANEL_NONE, 

0 ); 

(begin processing events, etc...) 

panel_set( iteml, PANEL_ITEM_X , 10, PANEL_ITEM_Y , 50, 0); 
panel_set( iteml, PANEL_LABEL_IMAGE, &pixrectl, 0); 
panel_set( iteml, PANEL_VALUE_DISPLAY_LENGTH, 30, 0); 
panel_paint (iteml, PANEL_CLEAR) ; 

v J 
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Example 2: 





item2 = panel_create_item(panel , PANEL_TEXT, 

PANEL_LABEL_STRING , "Enter Name:", 

PANEL_VALUE_DISPLAY_LENGTH, 10, 

0 ); 

(begin processing events, etc...) 

panelset ( item2 , 

P ANEL_I TEM_X , 10, 

PANEL_ITEM_Y, 50, 

PANEL_PAINT , PANEL_NONE, 

0 ); 

panel_set ( item2 , 

PANEL_LABEL_ IMAGE, &pixrectl, 

PANEL_PAINT , PANEL_NONE , 

0 ); 

panel_set ( item2 , 

PANEL_VALUE_DISPLAY_LENGTH, 30, 

0 ); 

v ) 



The above two examples each produce the same effect. In the first example, the 
item’s repaint behavior is set to PANEL_NONE at creation time, so it is not 
repainted automatically after the panel_set ( ) calls, and no repainting occurs 
until the call to panel_paint ( ) . In the second example, the item’s repaint 
behavior is the default, PANEL_CLEAR. This is overridden in the first two 
panel_set ( ) calls, so no repainting occurs. However, it is not overridden in 
the third call to panel_set ( ) , so repainting occurs before that call returns. 

As mentioned above, the repaint behavior for all items in a panel can be set when 
the panel is created, e.g.: 



window_create( frame, PANEL, PANELPAINT, PANEL_NONE, 0); 
v 



All items created in the above panel will have a repaint behavior of 
PANEL NONE. 
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You can iterate over each item in a panel with the two attributes 
PANEL_FIRST_ITEM and PANEL_NEXT_ITEM. A pair of macros, 
panel_each_item( ) and panel_end_each are also provided for this 
purpose. For example, to destroy each item in a panel you would call: 




NOTE Parentheses are not required around the statements to be executed on each itera- 
tion. Also, a semicolon is not required after panel_end_each. 

9.12. Panel Item Client One attribute applicable to items of all types which should be mentioned is 

Data PAN E L_C L I E NT_D AT A. You can use this attribute in a variety of ways. 

Perhaps the most common use is to associate a unique identifier with each item. 
This is convenient in the case where you have many items, or where you are 
creating and destroying items dynamically. If you need to pick one item out of 
all the items, you can store an identifier (or a class) with it via 
PANEL_CLIENT_DATA, and then query the item directly to find out its 
identifier or class. 

The detool program in Appendix A, Example Programs , demonstrates this use of 
PAN E L_C L I E NT_DAT A. The panel buttons for its number keys 0-9 share the 
same notify procedure. Each button’s PANEL_CLIENT_DATA holds the ASCII 
digit displayed on the button; when a button is pushed, the 
PANEL_CLI ent_dat A is retrieved and displayed on the “screen” of the calcu- 
lator. This saves having a different notify procedure for every button. 

You can also use PAN E L_C LIEN T_D AT A to associate a pointer to a private 
structure with an item. For one example of this usage, see the example in the 
next section under Writing Your Own Event Handler. Another application would 
be to link several items together into a list which is completely under your con- 
trol. 



9.11. Iterating Over a 
Panel’s Items 
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9.13. Event Handling 



Default Event Handling 



Writing Your Own Event 
Handler 



This section describes how the panel package handles events. 61 If you require a 
behavior not provided by default, you can write your own event handling pro- 
cedure for either an individual item or the panel as a whole. 

Using the default event handling mechanism, events are handled for all the panel 
items in a uniform way. A single routine reads the events, updates an internal 
state machine, and maps the event to an action to be taken by the item. Actions 
fall into two categories: previewing and accepting. The previewing action gives 
the user visual feedback indicating what will happen when he releases the mouse 
button. The accepting action causes the item’s value to be changed and/or its 
notify procedure to be called, with the event passed as the last argument. 



The default event-to-action mapping is given in the following table: 



Event 


Action 


Left button down or drag in w/left button down 


Begin previewing 


Drag with left button down 


Update previewing 


Drag out of item rectangle with left button down 


Cancel preview 


Left button up 


Accept 


Right button down 


Display menu & accept user’s selection 


Keystroke 


Accept keystroke if text item 



What actually happens when an item is told to perform one of the above actions 
depends on the type of the item. For example, when asked to begin previewing, 
a button item inverts its label, a message item does nothing, a slider item redraws 
the shaded area of its slider bar, etc. 62 

You may want to handle events in a way which is not supported by this default 
scheme. For example, there is no way to take any action on middle mouse button 
events. To do so you must extend the event handling functionality by replacing 
the default event-to-action mapping function for a panel or panel item. Three 
attributes have been defined for this purpose: 



Table 9-3 Panel Event Handling Attributes 



Attribute 


Argument Type 


Default Value 


PANEL_EVENT_PROC 


int (*)() 


paneldef aulthandleevent ( ) 


PANEL_BACKGROUND_PROC 


int (*) ( ) 


panel def ault_handle event () 


PANEL_ACCEPT_KEYSTROKE 


boolean 


FALSE 



An item’s PANEL EVENT PROC is called when an event falls over the item. 
The event procedure for an item defaults to that for the panel. Thus you can 
change the event procedure for all the items in a panel by specifying your own 
PANEL_EVENT__PROC for the panel before the panel items are created. The 
arguments passed to the event procedure are the item (or panel) and the event 



61 The general SunView input paradigm, including details on the various events, is covered in Chapter 6, 
Handling Input. 

62 For particulars, see the Selection subsection under each item type. 
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The default event procedure, which implements the default event-to-action map- 
ping described on the previous page, is: 

panel_def ault__handle_event ( object , event ) 

<Panel_item or Panel> object ; 

Event * event; 

The panel’s PANEL_BACKGROUND_PROC is called when an event falls on the 
background of the panel (i.e. an event whose locator position does not fall over 
any item). The default panel background procedure is also 
panel_def ault_handle_event ( ) ; however, the various actions are no- 
ops for the panel. Note that this attribute only applies to a panel; it has no mean- 
ing for an individual panel item. 

The attribute PANEL_ACCEPT_KEYSTROKE determines whether or not an item 
or panel is interested in keystroke events. If this is TRUE, the item or panel 
under the cursor is given keystroke events as they are generated. The default 
behavior sends all keystroke events to the text item with the caret, independent of 
the cursor position. 

In addition to the three event related attributes, three event codes have been 
defined: 

□ PANEL_EVENT_DRAG_IN — the item or panel was entered for the first 
time with one or more buttons down. 

□ PANEL_EVENT_MOVE_lN — the item or panel was entered for the first 
time with no mouse buttons down. 

□ PANEL_EVENT_CANCEL — the item or panel is no longer “current” so any 
operations in progress should be canceled (e.g. cancel previewing). 

The panel package will generate these events as appropriate and pass them to the 
item’s event procedure or the panel’s background procedure. 

The event-to-action mapping is performed by means of a set of action functions. 
If you haven’t specified an event procedure for the item, 
panel_def ault_handle_event ( ) will map events to the appropriate 
actions by calling one of the action functions. These action functions have been 
made public so that, if you replace the event procedure for an item, you can ask 
the panel package to perform one of the default actions by calling the 
corresponding action function from your new event procedure. 

The action functions are given in the table on the following page. 
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Example 



Table 9-4 Panel Action Functions 



Definition 




Description 


panel accept key(object, event) 
<Panel or Panel_item> object; 
Event *event; 


Tells a text item to accept a keyboard 
event. Currently ignored by non-text 
panel items. 


panel accept menu (object , event) 
<Panel or Panel item > object; 
Event * event; 


Tells an item to display its menu 
and process the user’s selection. 


panel accept preview ( object , 
<Panel or Panel_item > object; 
Event *event; 


event) 


Tells an item to do what it is supposed 
to do when selected, including completing 
any previewing feedback. 


panel begin preview(object , 
<Panel or Panel _item> object ; 
Event *event; 


event) 


Tells an item to begin any feedback 
which indicates tentative selection. 


panel cancel preview ( object , 
<Panel or Panel _item> object ; 
Event *event; 


event ) 


Tells an item to cancel any previewing 
feedback. 


panel update preview(ob ject , 
< Panel or Panel _item> object; 
Event *event; 


event) 


Tells an item to update its previewing 
feedback (e.g. redraw the 
slider bar for a slider item). 



In most of the action routines, only the event's location and shift state are of 
interest. When previewing, choices, toggles and sliders use the event’s location 
to determine the current value. Choices use the shift state to determine whether 
to advance or backup the current choice. panel_accept_key ( ) is the only 
action function to make use of the actual event code. 



Suppose you are implementing dbxtool and want to have the buttons in the com- 
mand panel execute different commands depending on whether they were 
selected with the left or middle mouse button. For example, the button labeled 
next might behave as the step button if activated with the middle button. When 
the middle button is depressed, you want to preview an alternate label, and when 
it is released, you want to execute the dbx command corresponding to the pre- 
viewed label. 



You can get this functionality by replacing the event procedure for each of the 
button items in the command panel. This could be done either by specifying a 
default event procedure for all the items when the panel is created: 





panel = window create ( frame, PANEL, 




A 




PANEL_EVENT_PROC , 
0); 


dbx event proc. 




1 






J 


or by specifying a the event procedure as each panel item is created: 




panel create item(panel, PANEL BUTTON, 








PANEL EVENT PROC, 


dbx_event proc , 






0); 












J 
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Whenever one of the buttons gets an event, dbx_event_proc ( ) will be 
called and can then map the events to actions as it sees fit. The code for the new 
event procedure is given below. Note the use of P ANEL_C LIE NT_D AT A to 
store the images for the two labels for each item. 

dbxeventproc ( item, event) 

Panel_item item; 

Event *event; 

{ 

struct dbxdata *dbx_data; /* data stored with each item */ 

Panel panel; 

/* First get my private data for this item. */ 

panel = (Panel) panel get ( item, PANEL_PARENT_PANEL) ; 

dbxdata = (struct dbx_data *) panelget ( item, PANEL_CLIENT_DATA) ; 

/* See if this is an event of interest. */ 
switch (event_action (event) ) { 

/* middle button went up or down */ 
case MS_MIDDLE : 

if ( event_is_down( event ) ) { 

/* middle button went down, so change the button's label 

* image to reflect its middle button action . 

V 

panel_set ( item, PANEL_LABEL_IMAGE, dbx_data->middle_pr , 0); 

/* now begin the normal previewing */ 
panel_begin_preview( item, event) ; 

} else { 

/* middle button went up, so accept the previewing */ 
panel_accept_preview( item, event) ; 

/* now change the image back */ 

panel_set ( item, PANEL_LABEL_IMAGE, dbx_data->left_pr, 0); 

} 

break; 

/* drag into item with button down */ 
case PANEL_EVENT_DRAG_IN: 

if (window_get (panel, WIN_EVENT_STATE, MS_MIDDLE) ) { 

/* middle button is down, so treat this as begin preview. 

*/ 

panelset ( item, PANELLABELIMAGE, dbx_data->middle_pr , 0); 
panel_begin_preview(item, event) ; 

} 

else 

/* we weren't previewing, so 

* let the default event proc handle it. 

*/ 

panel_def ault_handle_event ( item, event) ; 
break; 
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/* cancel for some reason */ 
case PANEL_EVENT_CANCEL : 

if (panel_get ( item, PANEL_LABEL_IMAGE ) == 
dbx_data->middle_pr ) { 

/* we were previewing -- cancel it. 

V 

panel_cancel_preview( item, event) ; 

panelset ( item, PANEL_LABEL_IMAGE , dbx_data->lef t_pr , 0); 
] else 

/* we weren't previewing, so 
* let the default event proc handle it. 

V 

panel_def ault_handle_event ( item, event ) ; 
break; 

/* some other event */ 
default : 

/* we don't care about this event -- let the default 
* event proc handle it. 

V 

panel_default_handle_event ( item, event) ; 

} 

} 



The final step is to modify the notify procedure for each button to perform dif- 
ferent actions depending on which mouse button was released. The notify pro- 
cedure for the step/next button, for example, would look like: 




Translating Events from In the case of a scrollable panel, the panel is larger than the subwindow in at least 

Panel to Window Space one dimension. If the panel has been scrolled, each point within the subwindow 

will have one location in the coordinate space of the panel and a different loca- 
tion in the coordinate space of the subwindow. Two functions are provided to 
translate event coordinates from panel space to window space, and vice versa. 

If you read your own events with window_read_event ( ) , 63 you must 
translate the events from window space to panel space with: 



63 window_read_event ( ) is described in Chapter 6, Handling Input. 
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Event * 

panel_event( panel, event) 

Panel panel; 

Event * event; 

To go from panel space to window space, use: 
Event * 

panel_window_event ( panel , event ) 
Panel panel; 

Event * event; 



Example 



Figure 9-7 illustrates the image browser from iconedit. It serves as an exam- 
ple of when to use panel_window_event ( ) . If the user presses the menu 
button over an image, then he gets a menu showing the name of the file contain- 
ing the image: 

Figure 9-7 Image Browser Subframe Using panel_window_event( ) 




In order for the menu to be displayed in the correct place in a panel which has 
been scrolled, the menu’s location must be specified in the coordinates of the 
subwindow, not of the panel. 
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The browser is implemented as a panel containing buttons having the images as 
their labels. The buttons are created each time the user wants to browse a dif- 
ferent set of images. When each button is created, the name of the file containing 
the image is stored as the value of the button’s PANEL_CLIENT_DATA. 

Listed below is the event procedure shared by each button. There is a global 
menu containing a single menu item, image_menu_item. If the event is a 
right mouse button, the display string for this menu item is set to the file name 
which was previously stored as the button’s panel_CLIENT_data. 

Then the event is adjusted from panel space to window space, and the menu is 
displayed at the proper coordinates. If the user selects from the menu, the 
button’s notify procedure, browser_items_notify_proc ( ) , is called, so 
the effect is the same whether the item is selected through the menu or directly. 





browser_items_event_proc ( item, event ) 

Panel_item item; 

Event * event; 

{ 

if (event_action ( event ) == MS_RIGHT) { 

Event *ad justed_event ; 
menu_set ( image_menu__item , 

MENU_STRING, panel_get ( i tern, PANEL_CLIENT_DATA) , 0); 

adjusted_event = panel_window_event (browser, event); 

if (menu_show(image_menu, browser, ad justedevent , 0)) { 
browser_items_notif y_proc ( item) ; 
return; 

} 

} 

panel_def ault_handle_event ( item, event) ; 

1 

v > 



Note that for all events other than the right mouse button, the panel’s default 
event procedure is called. 
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Alerts 



This chapter describes the alerts package, which you can use by including the file 
<s untool/alert . h> in your program. 

This chapter is divided into three logical sections. Section 1 provides a brief 
introduction to alerts. Section 2 explains the components that make up alerts. 
Sections 3 gives program fragments that introduce most of the alert attributes. 

10.1. Introduction to Alerts An alert is a pop-up frame that contains a panel to notify a user of problems or 

changes that require their attention. An alert is easily identified visually by a 
large black arrow that sweeps into the alert window from the left. A Sun View 
application can use alerts to notify a user that an event has taken place or to ver- 
ify that a user requested some action. Each alert that pops up has full screen 
access. That is, the screen is frozen until the user responds to the alert. 

Alerts are a replacement for the menu_prompt ( ) facility. Some programs will 
use menu prompts instead of alerts if the user disables alerts in 
def aultsedit. Menu prompts offer a simple box with text, and a maximum 
of two choices. 

Alerts, on the other hand, have a better user interface. Alerts provide an 
attention-getting alert arrow, buttons, fonts, beeps, a 3-D shadow, and so on. 
Using alerts, you can offer a user more than two choices of action. 

Summary Listing and Tables To give you a feeling for what you can do with alerts, the following page con- 
tains a list of the available alert attributes and functions. Many of these are dis- 
cussed in the rest of this chapter as they occur in the examples and elsewhere 
(use the Index to check). All are briefly described with their arguments in the 
alert summary tables in Chapter 19, SunView Interface Summary : 

□ the Alert Attributes. 

□ the Alert Functions and Macros. 
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Alert Functions 

alert_prompt(client_frame, event, attributes) 

Uses of Alerts A SunView application uses alerts to display messages to the user, who can then 

either continue, cancel, or choose a different course of action. Possible uses of 
alerts include the following: 

□ Querying whether an action was intended: “Are you sure you want to Quit?” 

o Notifying a user of a current state: “Unrecognized file name. No files match 
specified pattern.” 

10.2. The Components of Figure 10-1 illustrates the visible components that make up an alert. Each com- 
an Alert ponent is described below. 

Figure 10-1 An Alert 
Alert Arrow 

Text Message 




Alert Arrow 



Each alert window is identifiable as an alert by the large black arrow that sweeps 
into the window from the left. 



Multiple-Line Text Message 

Do you really want to exit SunView? 



A multiple-line text message describes why an alert appeared and what to do in 
order to continue. For example, if the user tries to quit SunView, an alert with 
the message, “Do you really want to exit SunView?”, will pop up. 



#sun 

Xr microsystems 



Revision A, of March 27, 1 990 










Chapter 10 — Alerts 1 87 



Buttons 
l Cancel ] 



Positioning 

Beeping 



10 . 3 . alert 



Buttons make it possible to give the user a choice of actions when warning them 
that an event has taken place. Each button is associated with a string that 
specifies an action. 

Many alerts have a default button which is indicated by a double outline (as in 
the Confirm button above). If an alert has a default button, then the pointer will 
jump to this button when the alert appears, so that clicking LEFT will take the 
default action. The pointer is moved back to its original position when the alert 
goes away. The user can disable pointer jumping by setting 
SunView/ Alert Jump Cursor to disabled in def aultsedit. 

You have three choices for alert placement. The alert may be screen-centered, 
client-centered, or client-offset. 

An alert may be specified to pop up with or without a beep. The default is to 
come up beeping the number of times that is specified in def aultsedit. You 
may set your alert to come up without a beep even if the user’s default 
SunView/Alert_Bell entry in def aultsedit is to come up beeping. 

prompt ( ) There is only one function in the alert package, alert_prompt ( ) ; it creates 
an alert, pops it up on the screen, handles user interaction, then takes down the 
alert and returns a value. 

int 

alert_prompt(client_frame, event, attributes) 

Frame client_frame; 

Event * event 

<attribute-list> attributes ; 

alert_prompt ( ) displays an alert whose appearance and behavior is 
specified by the attribute value list attributes. It does not return a value 
until the user pushes a button in the alert or the default trigger event or its 
accelerator is seen. By default the alert is positioned over the center of 
client_f rame. 

If you supply a pointer to an event as event, it will be filled in with the user 
event which dismissed the alert. For example, if the users pushes a button by 
clicking LEFT, event_action ( event ) will be MS__LEFT . 64 

The possible status values which alert prompt ( ) returns are: 

□ ALERT_YES — the user pushed the “yes” alert button 

□ ALERT_NO — the user pushed the “no” alert button 

□ ALERT_FAILED — the alert_prompt ( ) failed for some reason 

□ ALERT_TRIGGERED — a triggered response occurred 



64 See Chapter 6, Handling Input for an explanation of the Events. 



microsystems 



Revision A, of March 27, 1990 






188 Sun V iew Programmer’ s Guide 



□ Some other integer — the user pushed some other button than “yes” or “no.” 

10.4. Building an Alert This section contains code fragments that illustrate most of the attributes for the 

alerts package. For a complete list and explanation of the alert attributes, see 
Chapter 19, SunView Interface Summary. Each code fragment described below 
is organized as follows: 

o Attributes introduced in the code are described 
o An illustration of the alert box is given 
a The code is listed and described. 

For a complete program example using alerts, see filer in Appendix A, Example 
Programs. 

Example 1 — Messages and This section gives two code fragments in order to illustrate the different button 

Simple Buttons attributes. The buttons allow the user to choose an action. Each alert may contain 

one or more buttons; the default is for no buttons. 

Each button has a name and an associated value. When a user pushes a button, 
the value associated with the button is returned. 

The following attributes are used in the first code fragment. STRINGS "" 
ALERT_MESSAGE_STRINGS 

The ALERT_MESSAGE_STRINGS attribute specifies a string or strings to be 
displayed in the message area of the alert panel. 

An example of the syntax for a message is: 

ALERT_MESSAGE_STRINGS , 

"The text has been edited.", 

"Empty Document will discard these edits. Please confirm", 

0 , 



The ALERT_BUTTON attribute displays a string in a button and associates a 
value to it. The value specified with the string is returned when the button is 
pushed. The value may be any integer, but should not be one of the values 
predefined by the alerts package ( ALERT_YES, ALERT NO, ALERT FAILED, 
or ALERT_TRIGGERED ). Figure 10-2 illustrates an alert that was built using 
the attributes ALERT_BUTTON. It contains four buttons and one text string. 

This example asks the user what part of the country he or she is from. The pro- 
gram fragment is listed below. 

Figure 10-2 A Simple Alert 
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Yes and No Buttons 




What part of the country are you from? 



f North) 



( South] 



[East] 







result = alert_prompt( 

(Frame) client_frame, 

(Event*) NULL 
ALERT_MESSAGE_STRINGS 

"What part of the country are you from?", 

0 , 



ALERT_BUTTON , 


"North" , 


101, 


ALERT_BUTTON , 


"East" , 


102, 


ALERT_BUTTON , 


"West" , 


103, 


ALERT_BUTTON, 


"South" , 


104, 


0); 







switch (result) { 
case 101: 

/♦handle case for someone from the North*/ 
break ; 
case 102: 

/♦handle case for someone from the East*/ 
break ; 
case 103 : 

/♦handle case for someone from the West*/ 
break ; 
case 104 : 

/♦handle case for someone from the South*/ 
break; 

case ALERT_FAILED : 

/* 

* Possibly out of memory or fds; 

* attempt to get information another way 
*/ 

break ; 

} ; 



Usually you will want to map your buttons to “yes” and “no” actions. To make 
this possible, two special buttons are triggered by predefined keyboard accelera- 
tors. Yes (confirm, do it) is mapped to the ( Return 1 key. No (cancel, don’t do it) 
is mapped to the [ Stop 1 key (usually I LI 1 ). 

The SunView event name for yes is ACTI0N_D0_IT. The SunView event 
name for no is ACTION STOP. 
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The following attributes are used in this example: 

The ALERT_BUTTON_YES attribute associates a string with the accelerated 
YES button indicating the “default” choice. The value ALERT_YES is returned 
by alert_prompt ( ) if the user pushes this button, or types f Return 1 . Only 
one instance of this attribute is allowed; subsequent instances are ignored. 

The YES button image will have a different button image than the other buttons. 
It will appear as a regular button image with a double outline. 

An example of the syntax is: 

ALERT_BUTTON_YES , "Confirm, discard edits " , 

The ALERT_BUTTON_NO attribute associates a string with the accelerated NO 
button. The value returned if the user pushes this button, or types ( Stop 1 , will be 
ALERT_NO. Only one instance of this attribute is allowed; subsequent instances 
are ignored. 

An example of the syntax is: 

ALE RT_BUTTON_NO , " Cancel " , 

Figure 10-3 illustrates the alert that is generated by the following code. It con- 
tains two buttons and two text strings. The buttons give the user two choices: to 
empty a document, discarding any edits, or to cancel the operation completely. 

Figure 1 0-3 A YES/NO Alert 




The text has been edited. 

Empty Document will discard these edits. Please confirm. 
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int result; 

result = alert_prompt ( 

(Frame)window, (Event*)NULL, 

ALERT_MESSAGE_ST RINGS, 

"The text has been edited.", 

"Empty Document will discard these edits. \ 

Please confirm.", 

0 , 

ALERT_BUTTON_YES, "Confirm, discard edits", 

ALERT_BUTTON_NO, "Cancel", 

0 ); 

switch(result ) { 
case ALERT_YES : 

/♦discard edits*/ 
break ; 

case ALERT_N0 : 

/♦cancel the Empty Document request */ 
break ; 

case ALERT_FAILED: 
break ; 

]; 

s, ) 



Example 2 — Changing Fonts The default font used for alert message text is the Client Frame’s font, if one has 

been specified; or else it is the same as SunView/Font. The default font for alert 
buttons is the same as that specified for menus in MenusIFont in defaultsedit, or 
screen.b.14, if no default is specified. 

You may prefer to use different fonts within alerts. For example, you might want 
to set off the text in an alert box from the text in the Client’s frame by using the 
bold version of the Client Frame’s default font. 

The ALERT_MESSAGE_FONT and ALERT_BUTTON_FONT attributes con- 
trol the font setting for the alert message text and alert buttons, respectively. 

Figure 10-4 illustrates an alert in which the message string is printed in 
courier.b.16. The code fragment shown below it illustrates how to set the 
attribute’s value using the font library. It also illustrates the use of multiple mes- 
sage strings. 



Figure 10-4 An Alert with Boldface Message Strings 




It's crackers to slip a rozzer 
the dropsy in snide , 
with a fuzzy udder. 

— Daimon Runyon 






t Cancel] 
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Event alert_event; 

int result = alert_prompt (base_f rame, &alert_event , 
ALERT_MESSAGE_STRINGS , 

"It's crackers to slip a rozzer", 

"the dropsy in snide, ", 

"with a fuzzy udder.", 

" --Daimon Runyon", 

0 , 

ALERTBUTTONYES , "Confirm", 

ALERT_BUTTON_NO , " Cancel " , 

ALERT_MESSAGE_FONT , 

pf_open ( "/usr/lib/fonts/f ixedwidthf onts/cour . b . 16 ) , 
ALERT_POSIT ION , ALERT_CLIENT_CENTERED, 

0 ); 

l 



Example 3 — Using Triggers Often you will want to give the user the choice of using mouse buttons or key- 
board accelerators instead of push buttons to respond to an alert. Triggers give 
you this option by making it possible to specify an accelerator or mouse action 
for a choice. 

For example, the text window uses an alert to ask the user where to split a win- 
dow. A left mouse button click is the trigger that responds to this alert. 

The following attribute is used when specifying a trigger: 

The ALERT_TRIGGER attribute allows the application to specify a SunView 
event which should cause the alert to return. The default is not to return a value 
unless a button has been pushed or the other YES/NO accelerators are seen. 

When an event is triggered, the value returned will be ALERT_TRIGGER. An 
example of the message syntax is as follows. 

ALERT_TRIGGER, event, 

Figure 10-5 illustrates the alert that is generated by the following code. This alert 
contains one button and a triggered response. When this alert comes up, the user 
may split the existing window into two windows, or can dismiss the alert by 
pushing the Cancel New Window button. This example also shows how alerts 
can effectively use an event to collect information about the way a user reacted to 
an alert. See Chapter 6, Handling Input , for a full explanation and list of all pos- 
sible events. 
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Figure 10-5 An Alert Using Triggers and Events 




Move pointer to where new view should 
begin, then click the left mouse button. 



Otherwise, push "Cancel Split View". 
[Cancel ^jiplit View! 




. 

Event event; 
int result; 

result = alert_prompt ( 

(Frame ) window, 

&event , 

ALERT_NO_BEEPING, 1, 

ALERT_MESSAGE_STRINGS , 

''Move pointer to where new window should", 

"appear, then click the left mouse button.", 

"Otherwise, push V'Cancel New Window. "\, 

0 , 

ALERT_BUTTON_NO, "Cancel New Window", 

ALERT_TRIGGER, MS_LEFT , 

0 ); 

switch (result) { 

case ALERT__TRIGGERED : 

(void) create_new_window_at_pos (eventx(Sevent) , 

event_y ( Sevent) ) , 

break; 

case ALERT_NO : 

break; /* don't create new window */ 
case ALERT_FAILED : 

/* alert failed, possibly out of memory or fds */ 




You may specify in your code to have an alert pop up without a beep as shown 
above. Generally, beeping is reserved for any event which occurs unexpectedly. 
If the alert is in response to a user request, it should not beep. 

The following attribute is used to specify no beeping for an alert. 

The ALERT NO BEEPING attribute allows the SunView application to specify 
that no beeping should take place regardless of def aultsedit setting. The 
default for this option is FALSE; that is, beep as many times as the defaults data- 
base specifies. 
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TTY Subwindows 



The tty (or terminal emulator ) subwindow emulates a standard Sun terminal, the 
principal difference being that the row and column dimensions of a tty subwin- 
dow can vary. You can run arbitrary programs in a tty subwindow; perhaps its 
main use is to run a shell within a window. 

To see tty subwindows in use, run the standard tools shelltool(l) and 
gfxtool(l). 

Header Files Programs using tty subwindows must include the file <suntool/tty . h> . 

Summary Listing and Tables To give you a feeling for what you can do with tty subwindows, the following 

page contains lists of the available tty subwindow attributes, functions and mac- 
ros. Many of these are discussed in the rest of this chapter and elsewhere (use the 
Index to check). All are briefly described with their arguments in the tty subwin- 
dow summary tables in Chapter 19 , SunView Interface Summary : 

□ the TTY Subwindow Attributes , 

□ the TTY Subwindow Functions , 

□ the TTY Subwindow Special Escape Sequences. 
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TTY Subwindow Attributes 


TTY_ARGV 


TTY_PAGE_M0DE 


TTY_PID 


TTY_C0NS0LE 


TTY_TTY_FD 


TT Y_QUI T_ON_CHI LD_DEATH 



TTY Subwindow Functions 

ttysw_input (tty, buf, len) tty sw_output ( tty , buf, len) 



4^sun 

microsystems 



Revision A, of March 27, 1990 









Chapter 1 1 — TTY Subwindows 1 97 



11.1. Creating a TTY 
Subwindow 



11.2. Driving a TTY 
Subwindow 



ttysw_input ( ) 



Like all SunView windows, you create a tty subwindow by calling 

window_create ( ) with the appropriate type parameter, as in: 
. 

Tty tty; 

tty = window_create ( frame, TTY, 0); 

V 



By default, the tty subwindow will fork a shell. If you want to start the tty 
subwindow with another program, say vi, you can do so by specifying the name 
of the program to run via the TTY_ARGV attribute: 

>. 

#include <suntool/sunview . h> 

#include <suntool/tty . h> 

char *my_argv[] = { "vi", 0 }; 

main ( ) 

{ 

Tty tty; 

Frame frame; 

frame = window_create ( 0 , FRAME, 0); 

tty = window_create( frame, TTY, TTY_ARGV, my_argv, 0); 
window_main_loop( frame) ; 

] 

v > 



NOTE You can only have one tty subwindow per process. 

You can drive the terminal emulator programmatically. There are procedures 
both to send input to the terminal emulator (as if the user had typed it in the tty 
subwindow) and to send output (as if a program running in the tty subwindow 
had output it). The two effects are similar to the mapi / mapo functions in 
~/ . ttyswrc that permit a user to bind a character sequence to a function 
key . 65 

You can send input to a tty subwindow programmatically with the function: 
int 

tty sw_input ( tty , buf, len) 

Tty tty; 
char *buf; 
int len; 

ttysw_input ( ) appends the character sequence in buf that is len charac- 
ters long onto tty’s input queue. It returns the number of characters accepted. 
The characters are treated as if they were typed from the keyboard. 
ttysw_input ( ) provides a simple way for a window program to send input to 
a program running in its tty subwindow. 



65 See shel ltool(l) in the SunOS Reference Manual. 
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ttysw_output ( ) 



Example: tty jo 

11.3. TTY Subwindow 
Escape Sequences 

Standard ANSI Escape 
Sequences 



Use ttysw_output ( ) to output to a tty subwindow, 
int 

ttysw_output( tty, buf, len) 

Tty tty; 
char *buf; 
int len; 



ttysw output ( ) runs the character sequence in buf that is len characters 
long through the terminal emulator of tty. It returns the number of characters 
accepted. The effect is similar to executing 



echo character sequence > /dev/ttyA 


\ 


v 


) 



where ttyiV is the pseudo-tty associated with the tty subwindow. One use of 
ttysw_output ( ) is to send the escape sequences listed in the next section to 
the tty sub window. 



Appendix A, Example Programs , gives the listing for tty jo, a program which 
uses ttysw_output ( ) to output strings of characters to a tty subwindow. 



The tty subwindow accepts the same ANSI escape sequences as the raw Sun con- 
sole, 66 with the following few exceptions: 

□ The effect of the bell control character CTRL - G(0x07)inatty subwindow 
depends on how the user has set the two options Audible Bell and 
Visible_Bell in the SunView category in def aultsedit(l). If 
Audible _Bell is Enabled, the bell will ring. If Visible_Bell is Enabled, the 
window will flash. 

□ The graphics rendition sequences ESC [ 4m (underline) and ESC [ lm (bold 
“extra-bright”) operate correctly. On the Sun console, these sequences 
always invert subsequent characters, whereas the tty subwindow only inverts 
when sent ESC [ 7m (stand-out). 

□ The effect of the bold “extra-bright” graphics rendition sequence ESC [ lm in 
a tty subwindow depends on the user’s setting for the Boldstyle option in 
the Tty category of def aultsedit. 

□ Unsupported graphics rendition mode escape sequences have the same effect 
as that chosen for bold “extra-bright”. On the Sun console, everything 
inverts. 

□ The Set Scrolling sequence ESC [ Or, which enables vertical wrap mode on 
the Sun terminal, has no effect in a tty subwindow. 



66 See the console(4s) manual page in the SunOS Reference Manual for a full list of escape sequences. 
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Special Escape Sequences Escape sequences have been defined by which the user can get and set attributes 

of both the tty subwindow and the frame which contains it. For example, the 
user can type an escape sequence to open, close, move or resize the frame, 
change the label of the frame or the frame’s icon, etc. These escape sequences 
are described in Table 19-35, TTY Subwindow Special Escape Sequences, in 
Chapter 19, SunView Interface Summary. 

Example: tty Jo For an example of setting the frame’s label via a tty subwindow escape sequence, 

see the program tty Jo, listed in Appendix A, Example Programs. 

11.4. Reading and Writing You cannot use the tty subwindow’s file descriptor returned by WIN FD to read 
to a TTY Subwindow and write characters to it. You can use tty_tty_FD attribute to get the file 

descriptor of the pseudo-tty associated with the tty subwindow. You can then 
use this to read and write to the pseudo-tty using standard UNIX I/O routines. 
Note that TTY_TTY_FD is the file descriptor of the pseudo-tty, not the file 
descriptor of the tty subwindow returned by WIN_FD. The latter is used for 
low-level window manipulation procedures. 

11.5. The Program in the You use the tty_argv attribute to pass the name of the program to run to the 

TTY Sub window tty subwindow. The program runs as a forked child in the tty subwindow. 

TTY PID You can use TTY_PID to monitor the state of the child process running in the tty 

window via the Notifier using notif y_interpose_wait3_f unc ( ) . The 
client’s wait3 ( ) function gets called when the state of the process in the tty 
subwindow changes. The setup is something like this: 




The wait 3 ( ) function can then do something useful, such as destroying the 
tty window or starting up another process in the tty subwindow. Here is a code 
fragment that detects the death of its tty subwindow’s child. It turns off the 
default behavior of a tty subwindow, which is to quit when the child process dies. 
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You can set TTY_PID as well as get it, but if you set it then you are responsible 
for setting the not if y_interpose_wait3_f unc ( ) to catch the child’s 
death, and for making the standard input and standard output of the child go to 
the pseudo-tty. 

Talking Directly to the If you set TTY_ARGV to TTY_ARGV_DO_NOT_FORK, this tells the system not 

Subwindow to fork a child in the tty subwindow. In combination with TTY_TTY_FD, this 

allows the tool to use standard I/O routines to read and write to the tty subwin- 
dow. 3 This simplifies porting terminal-oriented graphics programs, which 
interact with the user on the model of write a prompt . . . read a reply, to Sun- 
View. However, in most cases you should redesign programs to use a real win- 
dowing interface made up of SunView components. 

An Example The typein program in Appendix A, Example Programs, reads and writes directly 

to its tty subwindow, using SunView’s window_main__loop ( ) control struc- 
ture. 

The following example preserves the flow of control of a typical UNIX applica- 
tion, using notif y_do_dispatch ( ) to ensure that the Notifier gets called. 
Read Section 17.6, Porting Programs to SunView, for more information on using 
the Notifier in this way. 

' "" ' ' """ l 

#def ine BUFSIZE 1000 
static int my_done; 

static Notify_value 
my_ n °ti ce _d e st r °y (frame, status) 

Frame frame; 

Destroy_status status; 
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int argc; 

char *argv[]; 

{ 

Frame base_frame; 

Tty ttysw; 

int tty_fd; 

char buf [BUFSIZE] ; 

my_done = 0 ; 

base_frame = window_create (NULL, FRAME, 

FRAME_ARGC_PTR_ARGV , &argc, argv, 

0 ); 

ttysw = window_create(base_f rame, TTYSW, 

TTY_ARGV, TTY_ARGV_DO_NOT_FORK, 

0 ); 

tty_fd = (int )window_get (ttysw, TTY_TTY_FD) ; 
dup2(tty_fd, 0); 
dup2(tty_fd, 1); 

(void) notify_interpose_destroy_func (base_f rame, my_notice_destroy ) ; 
window_set (base_f rame, WIN_SHOW, TRUE, 0); 

(void) notify_do_dispatch( ) ; 

puts ( prompt _to_user ) ; 

while (gets (buf)) { 

if (my_done) /* continue until destroyed */ 
break; 

/* 

* This is where the meat of the program 

* would be if this were a real program. 

*/ 

puts (buf) ; 

} 

exit (0 ) ; 

1 

< > 



wanted a window program to read and write from its own tty subwindow. 
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Menus 



The SunView menu package allows you to chain individual menus together into 
a collection known as a walking menu. A menu contains menu items, some of 
which may have a small arrow pointing to the right. This indicates to the user 
that if he or she slides the mouse to the right of that item, a pull-right menu will 
appear. Menus can be strung together in this fashion, so that the user “walks” to 
the right down the chain of menus in order to make a selection. 

The definitions necessary to use walking menus are found in the file 
<suntool/walkmenu . h>, which is included by default when you include 
the file <suntool/sunview . h>. 

The most useful sections to read first are the first three. Section 12.1, Basic 
Menu Usage, introduces the basic routines and gives some simple examples. 
Section 12.2, Components of Menus & Menu Items, outlines the components of 
menus and menu items and introduces common terms. Section 12.3, Examples, 
gives more examples of using menus. Section 12.7, Callback Procedures, is for 
advanced users who need to understand the subtleties of the callback mechanism. 

The listing for fontjnenu, a program which builds on some of the examples 
given throughout the chapter, is given in Appendix A, Example Programs. 

Summary Listing and Tables To give you a feeling for what you can do with menus, the following two pages 

list the available menu attributes, functions and macros. Many of these are dis- 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the menu summary tables in Chapter 
19, SunView Interface Summary : 

a the Menu Attributes, 

□ the Menu Item Attributes, 

□ the Menu Functions. 
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Menu Attributes 


MENU_ACTION_IMAGE 




MENU_LAST_EVENT 


MENU_ AC T I ON I T EM 




MENU_LEFT_MARG IN 


MENU_ AP PEND_ ITEM 




MENU_MARGIN 


MENU_BOXED 




MENU_NCOLS 


MENU_CENTER 




MENU_N ITEMS 


MENU_CLIENT_DATA 




MENU_NROWS 


MENU_COLUMN_MAJOR 




MENU_NOTIFY_PROC 


MENU_CLI ENT_DAT A 




MENU_NTH_I TEM 


MENU_DESCEND_FIRST 




MENU_PARENT 


MENU_DEFAULT 




MENU_PULLRIGHT_DELTA 


MENU_DEFAULT_ITEM 




MENU_PULLRIGHT_IMAGE 


MENU_DEFAULT_SELECTION 




MENU_PULLRIGHT_ITEM 


MENU_FI RST_EVENT 




MENU_REMOVE 


MENU_F0NT 




MENU_REMOVE_ITEM 


MENU_GEN_PROC 




MENU_REPLACE 


MENU_GEN_PULLRIGHT_IMAGE 




MENU_REPLACE_ITEM 


MENU_GEN_PULLRIGHT_ITEM 




MENU_R I GHT_MARG I N 


MENU_IMAGE_ITEM 




MENU_SELECTED 


MENU_IMAGES 




MENU_SELECTED_I TEM 


MENU_INITIAL_SELECTION 




MENU_SHADOW 


MENU_I NI T I AL_SELECT I ON_EXP ANDED 




MENU_STAY_UP 


MENU_INITIAL_SELECTION_SELECTED 




MENU_STRINGS 


MENU_INSERT 




MENU_STRING_ITEM 


MENU_ INSERT_ITEM 




ME NU_T I T LE_ I MAGE 


MENU_ITEM 




MENU_TITLE_ITEM 


MENU_JUMP_AFTER_NO_S ELECT I ON 




MENU_TYPE 


MENU_JUMP_AFTER_SELECTION 




MENU_VALID_RESULT 



Menu Item Attributes 


MENU_ACTION_IMAGEf 




MENU_INACTIVE 


MENU_ACTION_ITEMf 




MENU_INVERT 


ME NU_AC T 1 0 N_P ROC 




MENU_LEFT_M ARG I Nf 


ME NU_ A P P E ND_ I T EMf 




MENU_MARG I Nf 


MENUJBOXEDf 




MENU_PARENTf 


ME NU_C ENT E Rf 




MENU_PULLRIGHT 


ME NU_C L I EN T_D A T Af 




MENU_PULLRIGHT_IMAGEf 


MENUFEEDBACK 




MENU_PULLRIGHT_I TEMf 


MENU_FONTf 




MENU_RELEASE 


MENU_GEN_PROCf 




MENU_RELEASE_IMAGE 


MENU_GEN_PROC_IMAGE 




MENU_R I GH T_M ARG I Nf 


MENU_GEN_PROC_I TEM 




MENU_SELECTEDf 


MENU_GEN_PULLRIGHT 




MENU_STRI NGf 


MENU_GEN_PULLRIGHT_IMAGEf 




MENU_S T R I NG_ I T EMf 


MENU_GEN_PULLRIGHT_I TEMf 




MENU_TYPEf 


MENO_IMAGE 




MENU_VALUE 


MENU_IMAGE_I TEMf 
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Menu Functions 

menu_create ( attributes ) 
menu_create_item( attributes > 
menu_des troy ( menu_ob j ect ) 

menu_destroy_with_proc (menu_ob j ect , destroy_proc ) 
void ( *destroy_proc) ( ) ; 
menu_f ind(menu, attributes) 
menu_set (menu_ob ject , attributes ) 
menu_show ( menu , window, event, 0) 
menu_return_item(menu, menu_item) 
menu_return_value (menu, menu_item) 
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12.1. Basic Menu Usage The basic usage of menus is to first create the menu with menu_create ( ) , 

then display it when desired with menu_show ( ) : 

Menu 

menu_create ( attributes ) 

<attribute-list> attributes; 

caddr_t 

menu_show(menu, window, event, 0) 

Menu menu ; 

Window window; 

Event * event; 

Like the creation routines for other SunView objects, menu_create ( ) takes a 
null-terminated attribute list and returns an opaque handle. menu_show( ) 
displays the menu, gets a selection from the user, and, by default, returns the 
value of the menu item the user has selected, window is the handle of the win- 
dow over which the menu is displayed; event 68 is the event which causes the 
menu to come up. The final argument is provided so that attributes may be 
passed in the future; at present it is ignored. 

Use the routines menu_set ( ) and menu_get ( ) to modify and retrieve the 
values of attributes for both menus and menu items: 

int 

menu_set (menu_ob ject, attributes ) 

<Menu or Menu_item> menu_ob j ect ; 

<attribute-list> attributes ; 

caddr_t 

menu_get (menu_object, attribute [ , optional_arg] ) 

<Menu or Menujtem> menu_ob j ect ; 

Menu_attribute attribute; 
caddr_t optional_arg; 

menu_set ( ) returns FALSE if the caller passes in NULL pointer instead of a 
menu. It returns allTRUEif 

All the attributes applying to menus and menu items are listed in the two 
corresponding tables Menu Attributes and Menu Item Attributes in in Chapter 19, 
SunView Interface Summary. Common attributes applying to both menus and 
menu items appear in both tables. 

The pages which follow contain three examples of basic menu usage. 



68 Canvases and panels have their own coordinate spaces separate from the window’s coordinate space. 
Note that event is in the coordinate space of the window, not of the canvas or panel. 
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Example 1: 



Let’s take a very simple example — a menu with two selectable items 
represented by the strings ‘On’ and ‘Off’: 



on_off_menu = menu_create(MENU_STRINGS , "On", "Off", 0, 

0 ) ; 



The attribute MENU_STRINGS takes a list of strings and creates an item for each 
string. Note that the first zero in the above call terminates the list of strings, and 
the second zero terminates the entire attribute list. 

CAUTION The menu package, in contrast to the panel package, does not save strings 
which you pass in. So you should either pass in the address of a constant, as in 
the example above, or static storage, or storage which you have dynamically allo- 
cated. 

Typically you call menu_show( ) from an event procedure, 69 upon receiving 
the event which is to cause display of the menu. In the code fragment below, we 
display the menu on right button down: 

. 

case MS_RIGHT : 

menu_show(on_of f_menu , window, event, 0); 
break ; 

s J 




menu_show ( ) , by default, returns the value of the item which was selected. If 
the item was created with MENU_STRINGS its value defaults to its ordinal posi- 
tion in the menu, starting with l. 70 So in the above example, selecting ‘On’ 
would cause 1 to be returned, while selecting ‘Off’ would cause 2 to be returned. 



You can specify that menu_show ( ) return the item itself, rather than return the 
value of the selected item. Do this by setting MENU NOTIFY PROC to the 
predefined notify procedure 71 menu_return_item ( ) , as in: 





menu_set (on_of f menu, 


A 




MENU NOTIFY PROC , menu return item. 






0); 








7 



69 See Chapter 6, Handling Inpul, for a discussion of event procedures. 

70 The value of menu items not created with MENU STRINGS defaults to zero. You can explicitly specify 
the values for menu items via the attributes MENU_IMAGE_ITEM, MENU_S TR I NG_I T EM, or ME NU_V ALU E. 

71 Notify procedures are covered in detail in Section 12.7, Callback Procedures. 
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Example 2: It’s easy to build up more complex menus out of simple ones. The next example 

creates a menu with two items, ‘Bold’ and ‘Italic’, each of which shares the on- 
off menu from the previous example as a pull-right: 



7 


menu = menu_create(MENU_ITEM, 




A 




MENU STRING, 


"Bold" , 






MENU_PULLRIGHT , 


on_of f_menu. 






0, 








MENU_ITEM, 








MENU_STRING, 


"Italic", 






MENU_PULLRIGHT, 


on off menu. 






0, 








0), 






^ 






J 



The most flexible way to create a menu item in-line in a menu create ( ) call 
is by using MENU_ITEM. In contrast to MENU_STRINGS, which allows you to 
specify only the display strings of the items, MENU_ITEM takes as its value a 
null-terminated attribute list which may contain any attributes applying to menu 
items. 72 

The value of MENU_STRI NG is the item’s display string; the value of 
MENU_PULLRIGHT is the handle of the item’s pull-right menu. (Note that you 
must already have created the menu before giving it as the value for 
MENU_PULLRIGHT.) 



Example 3: The menu package can accommodate images as well as strings. The example 

below creates a menu with a single item labelled ‘tools’. When the user pulls 
right, he brings up a menu showing the icons of three SunView tools — 
def aultsedit, iconedit, and fontedit. 



72 For a complete list of such attributes, see the Menu Item Attributes table in in Chapter 19, SunView 
Interface Summary. 
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In order to pass an image into the menu package you need a pointer to a memory 
pixrect containing the image. One common way to create such an image is by 
first using iconedit to create the image and save it to a file. You then include the 
file in your program, and use the mpr_static ( ) macro to create a memory 
pixrect: 



static short d_defaults[] = { 

#include <images/defaultsedit . icon> 

1 ; 

mpr_static (defaultspr , 64, 64, 1, d_defaults); 

static short d_icon[] = { 

#include cimages/iconedit . icon> 

}; 

mpr_static ( icon_pr , 64, 64, 1, d__icon); 

static short d_font[] = { 

#include <images/fontedit . icon> 

1 ; 

mpr_static ( f ont_pr , 64, 64, 1, d_font); 

tool_menu = menu_create (MENU_IMAGES, 

&def aults_pr , &icon_pr, &font_pr, 0, 

0 ); 

menu = menu_create(MENU_ITEM, 

MENU_STRING, "tools", 

MENU_PULLRIGHT, tooljmenu, 

0 , 

0 ); 

v / 



The attribute MENU_IMAGES is analogous to MENU_STRINGS. It takes a list of 
images (pointers to pixrects) and creates a menu item for each image. 
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12.2. Components of 

Menus & Menu Items 

Menus 

Visual Components 

Generate Procedures 
Notify Procedures 
Client Data 
Menu Items 

CAUTION 

Menu Items 

Representation on the Screen 



This section gives an overview of the most important components of menus and 
menu items. Detailed discussion and examples follow later in the chapter. 



The text for a menu is rendered in the menu’s font, which you may specify via 
menu font. A menu has a shadow, you can specify the shadow’s pattern, or 
disable the shadow entirely, via MENU SHADOW. You can give a title to a menu 
via MENU_TITLE_IMAGE or menu_title_item . 73 By default, a menu’s 
items are laid out vertically; you can specify that the items be laid out horizon- 
tally or in a two-dimensional matrix via MENU NCOLS and MENU_NROWS. 

You may specify a generate procedure for a menu, which will be called just 
before the menu is displayed. This allows you to implement context-sensitive 
menus by dynamically modifying the menu, or even replacing it entirely . 74 

The menu's notify procedure is called after the user makes a selection. By using 
a notify procedure, you can perform an action or alter the resultor alter the result 
to be returned by menu_show ( ) 75 . 

The menu’s client data field, accessible through MENU_CLIENT_DATA, is 
reserved for the application’s use. You can use this attribute to associate a 
unique identifier, or a pointer to a private structure, with a menu. 

A menu contains an array of items. To retrieve a menu’s nth item, use 
MENU_NTH__ITEM. To retrieve the total number of items in a menu use 
MENU_NITEMS. 

The same menu item can appear in more than one menu. 

Menu items, unlike panel items, are counted starting with one. 



A menu item is either displayed as a string or an image (a pointer to a pixrect). If 
the item has another menu associated with it using the MENU PULLRIGHT attri- 
bute, then it is a pull-right item. 



73 The title is nothing more than an inverted, non-selectable item. It does not automatically appear at the top 
of the menu — it is your responsibility to position it where you want it. 

74 See example 8 in Section 12.7, Callback Procedures, later in the chapter. 

75 Notify procedures are discussed in detail in Section 12.7, Callback Procedures. 
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Item Values 



Item Generate Procedures 



Item Action Procedures 



Client Data 



Each menu item has a value. By default an item's value is the initial ordinal 
position of the item if it was created with MENU STRINGS; otherwise the 
default value is zero. You can set an item's value explicitly when you create the 
item with MENU_STRING_ITEM or MENU_IMAGE_ITEM. You can also expli- 
citly set an item’s value with MENU_VALUE. However, if an item is a pull-right, 
then its MENU VALUE is the value of its pull-right menu. This means that only 
“leaf’ menu items without submenus have a true value. 

As mentioned in Section 12. 1, Basic Menu Usage, menu_show( ) by default 
returns the value of the item the user has selected. Since menu items are counted 
starting from one, a return value of zero from menu show ( ) would represent 
the null selection. 76 However, you may explicitly set the value of a menu item to 
zero. If you do, then a return value of zero could represent either a legal value 
for the selected item or an error. To tell whether or not the result was valid, call 
menu_get( ) with the boolean MENU_VALID_RESULT. A return value of 
TRUE means that the result was valid; FALSE means that the value is invalid. 

As with the menu as a whole, you may specify a generate procedure for each 
menu item, to be called just before the item is displayed. 

The action procedure of a menu item is analogous to the notify procedure of a 
menu. This is your chance to do something immediately based on the user’s 
selection. 

Menu notify procedures and item action procedures differ in when they are 
called. If the user chooses an item in a pull-right menu, the notify procedures (if 
any) for the menus higher up in the chain leading to the pull-right will be called, 
whereas the action procedures (if any) for the chosen menu item and menu items 
under it (“to its right”) will be called. 77 

Each menu item has a client data field, accessible through 
ME NU_C LIE NT_D AT A , which is reserved for the application’s use. You can use 
this attribute to associate a unique identifier, or a pointer to a private structure, 
with each menu item. 



76 This is why menu items are counted starting with one, rather than zero: so that a zero return value would 
represent the null selection whether the menu show ( ) was returning the value of the selected item or the item 
itself. 

77 Action procedures are discussed in detail in Section 12.7, Callback Procedures. 
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Item Margins The diagram below illustrates the layout of a menu item: 

Figure 12-1 Layout of a Menu Item 
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ME NU_MARG I N represents the margin, in pixels, around an item in a menu. Its 
default value is 1. 

You can set an individual item’s margin by setting the menu item. To set the 
margins for all items in a menu, set the menu’s margin. 

You can adjust the horizontal placement of text in menu items with 
MENU_LEFT_MARGIN and MENU_RIGHT_MARGIN. 78 

As with MENU_MARGIN, the left and right margins can be set either for an indi- 
vidual menu item or for the menu itself, in which case the settings will apply to 
all the items in the menu. (The attributes MENU_FONT and MENU_BOXED also 
work this way.) 



12.3. Examples 

Example 4: 




Our next example will show several variations on a simple menu that could be 
used for selecting font point sizes. The default form is shown to the left. 

You could create the items with MENU_STRINGS, as in the previous example. 
Alternately, you could create the menu with no items, then use menu set ( ) to 
append the items to the menu: 79 



m = menu_create(0) ; 

for (i = 8; i <= 18; i += 2) 

menu_set (m, MENtJ_STRING_ITEM, int_to_str ( i ) , i, 0); 

V ) 



78 The placement of images is currently not affected by the settings of the left and right margins. 

79 Note that using MENU_S T R ING_I TEM with menu_set ( ) has the effect of an implicit append. Several 
attributes are provided to explicitly add items to a menu — see Table 12-1 , Attributes to Add Pre-Existing Menu 
Items, later in this section. 
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MENU__STRING_ITEM takes as values the item’s string and its value. 

Now let’s see some of the ways in which the appearance of this basic menu can 
be altered. 

By setting MENU INACTIVE to TRUE for an item, you can “gray out” the item 
to indicate to the user that it is not currently selectable. 



The menu to the left could be produced by: 



— 


for 


(i = 


4; i <= 6; i++) { 


"\ 






item 


= menu__get (m, MENU_NTH_ITEM, i); 






] 


menu 


set (item, MENU_ IN ACTIVE, TRUE, 0); 










> 



Inactive items do not invert when the cursor passes over them. 

The call menu_set(m, MENU_BOXED, TRUE, 0 ) will cause a single- 
pixel box to be drawn around each item. With the default margin of 1 pixel, this 
will result in two-pixel lines between each item. 



Increasing the margin, by setting MENU MARGIN to 5, will cause the items to 
spread out evenly, and the boxes to appear as individual boxes rather than divid- 
ing lines. 



You can control the layout of the items within a menu with the attributes 
MENU NCOLS and MENU NROWS. Suppose you wanted the menu to be laid out 
horizontally instead of vertically: 



8 18 12 14 18 18 



All you need do is specify at create time that the menu will have 6 columns with 
a call such as menu_set ( m, MENU_NCOLS , 6 , 0 ) . 

You can use MENU_NCOLS or MENU_NROWS to create two-dimensional menus, 
as well. The call menu_set ( m, MENU_NCOLS , 3 , 0 ) will cause the 
menu package to begin a second row after the first three columns have been filled 
with items: 



8 18 12 

14 16 18 

wmMMMmmmmmm 
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The previous example specified that the menu have 3 columns. Specifying that it 
have 2 rows via MENU_NROWS would have the same effect. Items are laid out 
from upper left to lower right, in “reading order,” regardless of how the layout is 
specified. 




The only time you need to specify both the number of rows and the number of 
columns is when you want to fix the size of the menu, regardless of how many 
items it contains. Setting MENU_NCOLS to 3 and MENU NROWS to 3 would pro- 
duce: 

If both dimensions of the menu are fixed and more items are given than will fit, 
the excess items will not appear. 



8 

18 

12 

14 

16 

18 



You can remove the menu’s shadow by setting MENU SHADOW to null: 

The menu package provides three predefined pixrects for the menu shadow. The 
call menu_set(m, MENU_SHADOW , &menu_gray25_pr ) producesthe 
25 percent gray pattern shown on first menu below. Note that these are pixrects, 
not pixrect pointers. The other two patterns are produced by using 
menu_gray50_pr and menu_gray75_pr: 





r&s&sss&sS 




Example 5: Let’s take the size menu from the previous example and use it to create the more 

complex menu shown below, which the user could use to select both a font fam- 
ily and a point size within the family. This illustrates the multiple usage of a sin- 
gle menu. Pulling right over any of the items in the family menu will bring up 
the menu for selecting point size, as shown on the left. 
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Courier 






Serif 


=»> 1 




RF'L 


8 




CUR 


18 


Screen 


12 



14 

16 

18 



By using MENU_ITEM, we can give each item in the font family menu its string, 

the font in which to render the string, and the size menu as a pull-right: 



family_menu = menu_create ( 

MENU_ITEM, 



MENU_STRING, 


"Courier" , 


MENU FONT, 


cour , 


MENU_PULLRIGHT , 


size menu, 


0, 




MENU_ITEM, 


MENUJSTRING, 


"Serif" , 


MENU_FONT, 


serif, 


MENU_PULLRIGHT, 


size_menu. 


0, 




MENU_ITEM, 


MENU_STRING , 


" aplAPLGI J" , 


MENU_FONT, 


apl , 


MENU_PULLRIGHT, 


size_jnenu. 


0, 




MENU_ITEM, 


MENU_STRING , 


"CMR" , 


MENU_FONT, 


cmr , 


MENU_PULLRIGHT , 


size_menu, 


0, 




MENU_ITEM, 


MENU_STRING, 


"Screen" , 


MENU FONT, 


screen 


MENU_PULLRIGHT , 


size_menu, 


0, 





V. J 



Suppose the font family menu had already been created, and we wanted to add 
the size menu as a pull-right to each item of the existing menu. We could do this 
using the attributes MENU_NITEMS and MENU_NTH_ITEM. The loop below 
iterates over each item in the menu, retrieving the item’s handle and setting the 
pull-right for the item: 



for (i = ( int )menu_get ( family_menu, MENU_NITEMS) ; i > 0; --i) 
menu_set (menu_get (family_menu, MENU_NTH_ITEM, i), 
MENU_PULLRIGHT , sizejmenu, 0); 

v ) 
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Example 6: 




You can insert new items into an existing menu with MENU_INSERT. For 
example, suppose you want to insert blank lines into the font family menu, to 
indicate grouping: 

You can do this by inserting non-selectable items into the menu: 


menu_set ( f amilymenu , 

MENU_INSERT, 

2 , 

menu_create_i tem ( MENUjSTRING , " " , 

MENUFEEDBACK, FALSE, 

0 ), 

0 ); 

menu_set ( f amily_menu , 

MENU_INSERT , 

5, 

menu_get ( f amily_menu, MENU_NTH_ITEM, 3), 

0 ); 

< > 



MENU_INSERT takes two values: the number of the item to insert after, and the 
new item to insert. Disabling MENU_FEEDBACK makes the item non-selectable. 

The above example uses menu_create_item( ) to explicitly create the item 
to be inserted. Usually menu items are created implicitly, using the attributes 
described in Table 12-2, Menu Item Creation Attributes, in the next section. 

NOTE menu_create_item( ) does not set the MENU_RELEASE attribute by 

default, so that the resulting item will not be automatically destroyed when its 
parent menu is destroyed. This is in contrast to implicitly created menu items — 
see Section 12.5, Destroying Menus. 



&sun 

microsystems 



Revision A, of March 27, 1 990 






Chapter 12 — Menus 217 



In addition to MENU_INSERT, there are several other attributes you can use to 
add pre-existing menu items to a menu. 80 They are summarized in the following 
table. 

Table 12-1 Attributes to Add Pre-Existing Menu Items 



Attribute 


Value Type 


Description 


MENU_APPEND_ITEM 


Menu_item 


Append item to end of menu. 


MENU_INSERT 


int, Menu_item 


Insert new item after nth item 
(use n=0 to prepend). 


MENU_INS ERT__ITEM 


Menu_item( old ) , 






Menu_item ( new ) 


Insert new item after old item. 


MENU_RE PLACE 


int, Menu_item 


Replace nth item with specified item. 


MENU_REPLACE_ITEM 


Menu_item(old), 






Menu_item( new) 


Replace old item with new item 
in the menu (old item is not replaced 
in any other menus it may appear in). 



80 To delete items from a menu, use MENU REMOVE or MENU_REMOVE_I T EM, described in the Menu 
Attributes table in in Chapter 19, SunView Interface Summary. 
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Example 7: 



For the next example we will attach the on-off, family and size menus of the pre- 
vious examples as pull-rights to a higher-level menu for selecting fonts: 



Frame =» 
Fami ly ={► 
Size =*► 



Bold 



Italid Off 








font_menu = menu_create ( 



MENU_PULLRI GHT_I TEM , 


"Frame" , 


f ramemenu. 


MENU_PULLRI GHT_I TEM , 


"Family" , 


family menu. 


MENU_PULLRIGHT_ITEM, 


"Size" , 


size_menu , 


MENU_PULLRIGHT_I TEM , 


"Bold", 


on_of f_menu. 


MENU PULLRIGHT ITEM, 
0); ' 


"Italic" , 


onof fmenu. 



MENU_PULLRIGHT_ITEM takes a string and a menu as values. It creates an 
item represented by the string and with the menu as a pull-right. 

Note that on_of f_menu is used as a pull-right for both the bold and the italic 
menu items, and that the size_menu appears both as a pull-right from main 
level fontjmenu and from each item in f amily_menu. This demonstrates 
that a menu may have more than one parent. However, recursive menus are not 
allowed — if Ml is a parent of M2, M2 (or any of its children) may not have Ml 
as a child. Displaying such a recursive menu will probably result in a segmenta- 
tion fault. 

The ‘Frame’ item takes as its pull-right the menu which has been retrieved from 
the frame using WIN_MENU. 

The program fontjnenu , printed in Appendix A, Example Programs, builds 
further on the above examples. 
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12.4. Item Creation The attribute menu_item, introduced in Example 2, suffices to create any type 

Attributes of menu item. However, several attributes are provided for convenience as a 

shorthand way to create items with common attributes. These attributes, along 
with the types of values they take and the type of item they create, are summar- 
ized in the following table: 

Table 12-2 Mem Item Creation Attributes 



Attribute 


Value Type 


Type of Item Created 


MENU_ACT I ON_I MAGE 


image, action proc 


Image item w/action proc. 


ME NU_ACT I ON_ ITEM 


char *, action proc 


String item w/action proc. 


MENU_GEN_PULLRIGHT_IMAGE 


Pixrect *, proc 


Image item with 
generate proc for pull-right. 


MENU_GEN_PULLRIGHT_ITEM 


char *, proc 


String item with 
generate proc for pull-right. 


MENU_IMAGE_I TEM 


Pixrect *, value 


Image item w/value. 


MENU_IMAGES 


list of Pixrect * 


Multiple image items. 


MENU_PULLRIGHT_IMAGE 


Pixrect *, Menu 


Image item w/pull-right. 


MENU_PULLRIGHT_ITEM 


char *, Menu 


String item w/pull-right. 


MENU_STRING_ITEM 


char *, value 


String item w/value. 


MENU_STRINGS 


list of char * 


Multiple string items. 



We could now create the menu in Example 2 more compactly by using 

MENU_PULLRIGHT_ITEM instead of MENU_ITEM: 


m = menu_create(MENU_PULLRIGHT_ITEM, "Bold", on_of f_menu, 

MENtJ_PULLRIGHT_ITEM, "Italic", on_off_menu, 

0 ), 

^ ) 
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12.5. Destroying Menus Both menus and menu items are destroyed with the function: 

void 

menu_de s troy ( menu_ob j ec t ) 

<Menu or Menujtem > menu_ob j ect ; 



CAUTION Watch out for dangling pointers when using a menu item in multiple menus. The 
attribute MENU RELEASE (which takes no value) controls whether or not a 
menu item is automatically destroyed when its parent menu is destroyed. 

MENU RELEASE is set to TRUE by default for menu items created in-line via 
the menu item creation attributes. This can lead to dangling pointers, if the same 
menu item appears multiple times, because calling menu destroy ( ) can lead 
to items being destroyed multiple times. This warning also applies to pull-rights 
which are used multiple times. To prevent this error, remove multiple 
occurrences of an item or pull-right before destroying a menu. 

Calling menu_destroy_with_proc ( ) instead of menu_des troy ( ) 
when you want to destroy a menu lets you specify a procedure to be called as the 
menu or menu item is destroyed, lets you specify a procedure to be called every 
time a particular menu or menu item is about to be destroyed: 

void 

menu_destroy_with_proc ( menu_ob j ect , des troy_proc ) 

<Menu or Menujtem > menu_ob j ec t ; 
void ( *destroy_proc) ( ) ; 

Your destroy procedure should be of the form: 

void 

destroy_proc(menu_object, type) 

<Menu or Menujtem> menu_ob j ect ; 

Menu_attribute type; 

For menus, menu_ob ject is the menu and the type parameter is 
MENU_MENU; for menu items, menu_ob ject is the item and the type param- 
eter is MENU ITEM. 
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12.6. Searching for a Menu The function menu_f ind ( ) lets you search through a menu (and its children) 
Item to find a menu item meeting certain criteria: 

Menu_item 

menu_f ind (menu, attributes); 

Menu menu ; 

<attribute-list> attributes; 



For example, the following call searches for the menu item whose string was 
“Load New File” menu_find( ) will return itNULLif 



r 




\ 




whose string was "Load New File" : 




\ 




) 



By default, menu_f ind ( ) uses a “deferred” search — searching all the items 
in a menu before descending into any pull-rights which may be present. By set- 
ting MENU_DESCEND_FIRST (which takes no value), you can force a depth- 
first search. 

If multiple attributes are given, menu_f ind ( ) will find the first item matching 
all the attributes. 

The following attributes are recognized by menu f ind ( ) : 



Table 12-3 



Menu Attributes Recognized by menu_f ind ( ) 



MENU_ACTION 

MENU_CLI ENT_DATA 

MENU_FEEDBACK 

MENU_FONT 

MENU_GEN_PROC 

MENU_GEN_PULLRIGHT 

MENU_IMAGE 

MENU INACTIVE 



MENU_INVERT 
MENU_LEFT_MARG IN 
MENU_MARG IN 
MENU_P AR ENT 
MENU_PULLRIGHT 
MENU_R I G HT_MARG IN 
MENU_STRING 
MENU VALUE 




microsystems 



Revision A, of March 27, 1990 







222 SunView Programmer’s Guide 



12.7. Callback Procedures When you call menu_show ( ) , the menu package displays the menu, gets a 

selection from the user, and undisplays the menu. The menu package allows you 
to specify callback procedures which will be called at various points during the 
invocation of the menu. These let you create and modify menus or respond to 
the user’s actions, on the fly, at the time the user brings up the menu. There are 
three types of callback procedures: generate procedures (so named because they 
are called before the menu or item is displayed, allowing the application to gen- 
erate or modify the menu on the fly), notify procedures (for menus) and action 
procedures (for menu items) which are called after the user has made a selection. 

Flow of Control in The callback mechanism gives you a great deal of flexibility in creating, combin- 

menu_show( ) ing and modifying menus and menu items. This flexibility comes at the price of 

some complexity, however. To take advantage of it, it is necessary to understand 
when the callback procedures are called after you invoke menu_show ( ) . 

For purposes of explanation, the diagrams below divide the process of displaying 
a menu and getting the user’s selection into two stages, the display stage and the 
notification stage. 
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Figure 12-2 Display Stage of Menu Processing 
Start menu_show ( ) 




To Notification Stage 
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Figure 12-3 Notification Stage of Menu Processing 



From Display Stage 




Return from menu_show( ) 



Generate Procedures The first argument to a generate procedure is either a menu or menu item depend- 

ing on whether it’s a MENU_GEN_PROC or a MENU_GEN_PROC_ITEM. Also 
passed in is an operation indicating at which point in the processing of the menu 
the generate procedure is being called. The operation parameter is of type 
Menu_generate, and may be MENU_DI SPLAY, MENU_DlSPLAY_DONE, 
MENU_NOTIFY or MENU_NOTIFY_DONE. 81 

NOTE The menu package uses the fullscreen access mechanism when displaying the 
menu. Writing to the screen while under fullscreen access will probably cause 
your program to deadlock, so your generate procedure should not access the 
screen when called with an operation of MENU_DI SPLAY or 
MENU DISPLAY DONE. 



81 For a detailed explanation of when the generate procedures are called in relation to the other callback 
procedures, see the diagrams in the next subsection. Flow of Control in menu_show ( ) . 
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Menu Item Generate Procedure 



Example 8: 




There are three types of generate procedures — menu item generate procedures, 
menu generate procedures, and pull-right generate procedures. A description 
and example of each is given below. 

A generate procedure attached to a menu item has the form: 

Menu_item 

menu_item_gen_proc ( item, operation) 

Menu_item item; 

Menu_generate operation; 

You can specify a menu item generate procedure via MENU_GEN_PROC. 



The most common use of menu item generate procedures is to modify the item’s 
display string. The program listed below registers a generate procedure, 
toggle_proc ( ) . If it has been called from the MENU_DI S PLAY stage of 
processing, it toggles the text of the ‘Redisplay' item on the frame menu. 



#include <suntool/sunview . h> 

Menuitem toggle_j>roc ( ) ; 
int toggle = 0; 

main ( ) 

{ 

Window frame = window_create (NULL, FRAME, 0); 
Menu menu = window_get ( frame, WIN_MENU) ; 

Menu_item item = menuf ind (menu, 

MENU_STRING, "Redisplay", 0); 

menu_set ( item , MENU_GEN_PROC, toggle_proc, 0); 
window_main_loop ( frame) ; 

1 

Menu_item 

toggle_proc (mi, op) 

Menu_item mi; 

Menu_generate op; 



t 



switch (op) { 

case MENU_DISPLAY : 
if (toggle) { 

menu_set (mi , 

MENU_STRING, "Redisplay has been seen", 

0 ); 

] else { 

menu_set (mi , 

MENU_STRING, "Redisplay", 

0 ); 

1 

toggle = Itoggle; 
break; 

case MENU_DISPLAY_DONE : 
case MENU NOTIFY: 
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Menu Generate Procedure 



Example 9: 



case MENU NOTIFY DONE: 



break ; 

1 

return mi; /* item handle always returned */ 




The ‘Zoom7‘Unzoom’ item in the SunView frame menu also uses this technique 
to toggle its display string. Note that since this item knows how to modify itself, 
you could put it in other menus and get the same behavior. A generate procedure 
for a menu item allows the application to be called even when it has no 
knowledge of or control over the call to menu show ( ) . 

A generate procedure attached to a menu has the form: 

Menu 

menu_gen_proc(m, operation) 

Menu m; 

Menu_generate operation; 

You can specify a menu generate procedure via the attribute MENU_GEN_PROC. 

We will take as an example a menu allowing the user to list different groups of 
files. When the user makes a selection, we generate a menu containing the 
correct set of files: 



List dot files=i> 


i 




clock 
shelltool 
iconedi t 
• 

■ 


List all files 





The relevant functions are listed on the next page. The first, 
initial ize_menu ( ) , creates the three menu items, giving each of them the 
generate procedure list_files( ), and a unique identifier as 
ME NU_C LIE NT_D AT A . 

Remember that list f iles ( ) is called in four different situations by 
menu_show( ) : 82 

□ When the operation is MENU DI SPLAY, the pull-right is being asked to 
display its menu, so list_f iles ( ) calls the function 
get_f ile_names ( ) (not shown) to get the appropriate list of file names, 



82 See the diagrams in the earlier subsection, Flow of Control in menushow ( ) . 
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and adds each name in the list to the menu. 

□ When list_f iles ( ) is called with operation set to 

MENU DISPLAY DONE, the menu of generated file names is no longer 
being displayed, list f iles ( ) cleans up by destroying the old menu of 
file names, replacing it with a fresh menu with the same generate procedure. 
It returns the handle of this new menu. 

□ When list_f iles ( ) is called with an operation of MENU_NOTIFY 
or MENU_NOTIFY_DONE, the menu is returned unaltered. 



#define DOT 0 
#define BIN 1 
#define ALL 2 

static void 
initialize_menu (menu ) 

Menu menu; 

{ 

m = menu_create(MENU_GEN_PROC, list_files, 
MENU_CLIENT_DATA, DOT, 

0 ); 

menu_set (menu, 

MENU_PULLRIGHT_I TEM , "List dot files", m, 

0 ); 

m = menu_create(MENU_GEN_PROC, list_files, 

MENU_CLIENT_DATA , BIN, 

0 ); 

menu_set (menu , 

MENU_PULLRIGHT_ITEM, "List bin dir", m, 

0 ); 

m = menu_create(MENU_GEN_PROC, list_files, 

MENU_CLIENT_DATA, ALL, 

0 ); 

menu_set (menu, 

MENU_PULLRIGHT_ITEM, "List all files", m, 

0 ); 



static Menu 

list_f iles (m, operation) 

Menu m; 

Menu_generate operation; 

{ 

char **list ; 
int directory; 

int i = 0 ; 

switch (operation) [ 
case MENU_DISPLAY : 

directory = ( int ) menu_get (m, MENU_CLIENT_DATA ) ; 
list = get_file_names (directory ) ; 
while (*list) 
menu_set (m, 

MENU_STRING_I TEM , *list++, i++, 

0 ); 

break ; 

v J 
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case MENU_D ISP L A Y_DONE : 

/* 

* Destroy old menu and all its entries. 

* Replace it with a new menu. 



*/ 

directory = ( int )menu_get (m, MENU_CLIENT_DATA ) ; 
menudes troy (m) ; 

m = menucreate (MENU_GEN_PROC, list files, 
MENU_CLIENT_DATA, directory, 

0 ); ‘ 



break; 



case MENU_NOTIFY: 
case MENU_NOTIFY_DONE: 
break; 



/* The current or newly-created menu is returned */ 
return m; 



Pull-right Generate Procedure You can postpone the generation of a pull-right menu until the user actually pulls 

right by specifying a pull-right generate procedure. A pull-right generate pro- 
cedure has the form: 

Menu 

pullr ight_gen_proc ( mi , operation ) 

Menu_item mi ; 

Menu_generate operation; 

Note that the pull-right generate procedure is passed the item, and returns the 
menu to be displayed. 

You can specify a menu item’s pull-right generate procedure with a call such as 



menu_set (menu_item, MENU_GEN_PULLRIGHT , my_pullright gen , 0); 

l ) 



Alternatively, you can use the attributes MENU_GEN_PULLRIGHT_IMAGE or 
MENU_GEN_PULLRIGHT_ITEM to give a menu both an itefn and the item’s 
generate procedure. 



If you want to get the existing menu for an item which has a pull-right generate 
procedure, retrieve the value of the item, as in: 



t 








menu = menu_get ( item, MENU_VALUE ) ; 








> 
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Notify/Action Procedures When the user selects a menu item by releasing the mouse button, the menu 

package calls back to any notify procedures or action procedures you have 
specified. Notify procedures and action procedures have the form: 

caddr_t 

notify_proc (m, mi) 

Menu m; 

Menu_item mi; 

The most common usage is to have action procedures for the items at the leaf 
nodes of the walking menu. The general mechanism described below is provided 
to allow your procedures to be called for non-leaf nodes as well. 

Imagine a chain of menus expanded out. Lookup of the notify/action procedures 
starts with the “oldest” menu, the one passed to menu show ( ) . If it has a 
notify procedure, that notify procedure is called, otherwise the default notify pro- 
cedure, menu_return_value ( ) , is called. Likewise, for each menu down 
the chain, until the menu with the selected item is reached. If the selected item 
has an action procedure, that action procedure is called. If the selected item is 
not on a leaf node, then action procedures for any items farther down the chain 
are also called. 

Let’s see what happens in the example to the left (assume that ‘On’ is the default 
item for the first menu): 

If ‘Italic’ was selected: 

□ no callback to the first menu’s notify procedure since an item in it is 
selected, 

□ callback to the action procedure for the ‘Italic’ item, 

□ no callback to the second menu’s notify procedure since it is further down 
the chain than the selected item, 

□ callback to the action procedure for the ‘On’ item. 

If ‘Off’ was selected: 

□ callback to the notify procedure for the first menu, since an item in a menu 
further down the chain than it is selected, 

□ no callback to the action procedure for the ‘Italic’ item, since it is above the 
selected item in the chain, 

□ no callback to the second menu’s notify procedure since an item in it is 
selected, 

□ callback to the action procedure for the ‘Off’ item. 

NOTE If you specify a notify procedure, it is your responsibility to propagate the 

notification to any menus further down in the chain. You can do this by calling 
menu_get ( mi , MENU_VALUE ) from your notify procedure. This gets the 
value of the selected menu item, and since the value of a pull-right item is the 
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value of its pull-right menu, this will make notify /action procedures further down 
the chain get called. 



12.8. Interaction with 
Previously Defined 
SunView Menus 



Walking Menus for frames and tty subwindows can be customized . 83 All menu 
items in these menus are “position-independent” — in other words the menus do 
not count on a given item having a certain position or being located in a particu- 
lar menu. This makes it possible for you to safely add new items (including 
pull-right submenus) to an existing menu. 



NOTE You should not use the client data field of items created by SunView packages, 
because the packages have pre-empted it for their own use. 



Using an Existing Menu as a The program fontjnenu, listed in Appendix A, shows how you can replace an 

Pull-right existing menu with your own menu which has the original menu as a pull-right. 

Making use of several of the examples given earlier in the chapter, it creates a 
font menu which allows the user to select the font family, point size, and whether 
or not the font is bold or italic. Meanwhile, the first item, labelled ‘Frame’, 
brings up the original frame menu: 





Close 


Fami ly 


Move =*> 


Size 


Resize => 


Bold 


Expose 


Italic 


Hide 




Redisplay 




Quit 



83 Remember that in order to have these packages use walking menus the user must have enabled the 
Walking_Menus option in SunView category of def aultsedit(l); in SunOS Release 4.0, this is the default. 
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12.9. Initial and Default Two special menu items are the default item (menu_default_item) and the 
Selections selected item (MENU_SELECTED_ITEM). The default item is simply a dis- 

tinguished item. The selected item is the item which was last selected. 

Two attributes are provided to control the behavior of a menu in regard to its ini- 
tial selection. If MENU_INITIAL_SELECTION_SELECTED is TRUE, the 
menu comes up with its initial selection selected — that is the selection is 
inverted and the cursor is positioned over it. If FALSE, the menu comes up with 
the cursor “standing off’ to the left and no selection highlighted. If 
MENU_INITIAL_SELECTION_EXPANDED is TRUE, when the menu comes 
up, it automatically expands any pull-rights which are necessary to bring the ini- 
tial selection up on the screen. 

Each menu also has an initial selection (MENU_INITIAL_SELECTI0N) and a 
default selection. (menu_default_selection). 

The distinction between the initial selection and the default selection is subtle. 
Suppose MENU_INITIAL_SELECTION_EXPANDED was TRUE, and the ini- 
tial selection was an item in a pull-right. When the menu comes up, it will be 
expanded to show the initial item as selected. However, if the user moves the 
cursor to the left, backing out of the pull-right, and then moves back to the right, 
bringing the pull-right up again, the item selected will be the default selection 
rather than the initial selection. 

When the user selects a pull-right item without bringing up the associated menu, 
it is as if he had brought the pull-right up and selected the default item. 

You can set the initial selection and the default selection independently — either 
can be set to the default item or the selected item. 
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The user can specify the values of certain menu attributes in the Menu category 
of def aultsedit(l). When a menu is created, for attributes not explicitly 
specified by the application program, the menu package retrieves the values set 
by the user from the defaults database maintained by def aultsedit. This 
allows the user the ability to tailor, to some extent, the appearance and behavior 
of menus across different applications. For example, he may want to change the 
type of shadow, or expand the menu margin, and so on. 

The attributes under def aultsedit control are listed in the following table. 



T able 12-4 User Customizable Menu A ttributes 



Attribute 


Default 


Description 


MENU_BOXED 


FALSE 


If true, a single-pixel box will be 
drawn around each menu item. 


MENU_DEFAULT_S ELECT ION 


ME NU_DE FAULT 


MENU_S ELECTED or MENU_DEFAULT. 


MENU_FONT 


screen. b. 12 


Menu’s font. 


MENU_INITIAL_SELECTION 


MENU_DEFAULT 


MENU_S ELECTED or MENU_DEFAULT. 


MENU_INITIAL_SELECTION_S ELECTED 


FALSE 


If TRUE, menu comes up with its initial 
selection highlighted. If FALSE, menu comes 
up with the cursor "standing off' to the left. 


MENU_INITIAL_SELECTION_EXPANDED 


TRUE 


If true, when the menu pops up, it auto- 
matically expands to select the initial selection. 


MENU_JUMP_AFTER_NO_S ELECTION 


FALSE 


If true, cursor jumps back to its 
original position after no selection made. 


MENU_JUMP_AFTER_S ELECTION 


FALSE 


If TRUE, cursor jumps back to its 
original position after selection made. 


MENU_MARG IN 


1 


The margin around each item. 


MENU__LEFT_MARGIN 


16 


For each string item, margin in addition to 
MENU_MARGIN on left 
between menu’s border and text. 


MENU_PULLRIGHT_DELTA 


9999 


# of pixels the user must move the cursor to 
the right to cause a pull-right menu to pop up. 


MENU_RIGHT_MARGIN 


6 


For each string item, margin in addition to 
MENU_MARGIN on right 
between menu’s border and text. 


MENU_S HADOW 


50% grey 


Pattern for menu’s shadow. 
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Cursors 



This chapter describes how to create and manipulate cursors? 4 A cursor is an 
image that tracks the mouse on the display. Each window in Sun View has its 
own cursor, which you can change with the cursor package. 

If it is installed on your system, you can run the demo 
/usr/demo/cursor_demo to see the effects of various cursor attributes. 

The source for this is in 

/usr/src/share/sun/suntool/cursor_demo . c. 

Header Files The definitions necessary to use cursors are found in the include file 

<sunwindow/win_cursor . h>, which is included by default when you 
include the file <suntool/sunview . h>. 

Summary Listing and Tables To give you a feeling for what you can do with cursors, the following page con- 
tains a list of the available cursor attributes and functions. Many of these are dis- 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the cursor summary tables in Chapter 
19, SunView Interface Summary : 

□ the Cursor Attributes, 

□ the Cursor Functions. 



84 The cursor is called the “pointer” in user-level documentation. 
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Cursor Attributes 


CURSOR_CROSSHAIR_BORDER_GRAVITY 


CURSOR_OP 


CURSOR_CROSSHAIR_COLOR 


CURSOR SHOW_CROSSHA IRS 


CURSOR_CROSSHAIR_GAP 


CURS0R_SH0W_CURS0R 


CURSOR_CROSSHAIR_LENGTH 


CURSOR_SHOW_HOR I Z_HA IR 


CURSORCROSSHAIROP 


CURSORSHOW VERT_H A I R 


CURSOR_CROSSHAIR_THICKNESS 


CURSOR_VERT_HAIR_BORDER_GRAVITY 


CURSOR_FULLSCREEN 


CURSOR_VERT_HAIR_COLOR 


CURSORHORI Z_HA I RBORDERGRAV I T Y 


CURSOR_VERT_HAIR_GAP 


CURSORHORI Z__HAIR_COLOR 


CURSOR_VERT_HAIR_LENGTH 


CURSOR_HORIZ_HAIR_GAP 


CURSOR_VERT_HAIR_OP 


CURSOR_HORI Z_HAIR_LENGTH 


CURSOR_VERT_HAIR_THICKNESS 


CURS0R_H0RI Z_HA I R_OP 


CURSOR XHOT 


CURSOR_HORIZ_HAIR_THICKNESS 

CURSOR_IMAGE 


CURSOR_YHOT 



Cursor Functions 

cursor_copy( src_cursor ) cursor_get (cursor, attribute) 

cursor_create( attributes) cursor_set( cursor, attributes) 

cur sor_destroy ( cursor ) 
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13.1. Creating and The basic usage of the cursor package is to first create a cursor with 

Modifying Cursors cursor_create ( ) , and then use this cursor as the value of the 

WIN_CURSOR attribute in your call to window_create ( ) . 

Cursor 

cursor_create ( attributes ) 

<attribute-list> attributes ; 

Once you have created a cursor, you can alter its attributes with 
cursor_set ( ) and read back its attributes with cursor get ( ) : 

void 

cursor_set( cursor , attributes) 

Cursor cursor; 

<attribute-list> attributes ; 

caddr_t 

cur sor_get ( cursor , attribute) 

Cursor cursor; 

Cursor_attribute attribute; 

If you want to change the cursor of a window that has already been created, you 
can first get the cursor from the window using window_get ( ) of 
WlN_CURSOR, then use cursor_set ( ) to change the cursor, and then use 
window_set ( ) of WlN_CURSOR to re-attach the cursor to the window. 

A copy of an existing cursor can be made with cursor copy ( ) : 

Cursor 

cursor_copy ( src_cur sor ) 

Cursor src_cursor; 

A cursor can be destroyed and its resources freed with cursor_destroy ( ) : 
void 

cur sordes troy ( cursor ) 

Cursor cursor; 



13.2. Copying and 

Destroying Cursors 



Example 1 : Creating a Window A common use tor cursors might be to create a canvas subwindow and have it 

with a Custom Cursor use the cursor of your choice, rather than the default arrow cursor: 
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This example creates a cursor “on the fly” and passes it into the 
window_create ( ) routine for use with the canvas. The attribute 
CURSOR_lMAGE is set to the a pointer to the pixrect we want to use (a diamond 
or bullseye, for example). All of the other cursor attributes default to the value 
shown in the attribute table. 

Example 2: Changing the Suppose you have already created a window and you want to change its cursor. 

Cursor of an Existing Window Let’s say you want to change the drawing op to PIX_SRC: 




CAUTION The cursor returned by window get ( ) is a pointer to a static cursor that 
is shared by all the windows in your application. So, for example, saving the 
cursor returned by window_get ( ) and then making other window system calls 
might result in the saved cursor being overwritten. 85 

It is safe to get the cursor, modify it with cursor set ( ) and then put the cur- 
sor back. If there is any chance that the static cursor will be overwritten, you 
should use cursor copy ( ) to make a copy of the cursor, then use 
cursor_destroy ( ) when you are done. 

13.3. Crosshairs Crosshairs are horizontal and vertical lines whose intersection tracks the location 

of the mouse. You can control the appearance of both the horizontal and vertical 
crosshairs along with the cursor image. For example, you can create a cursor that 
only shows the cursor image, or only the horizontal crosshair, or both the hor- 
izontal and vertical crosshairs and the cursor image. By default both the 
crosshairs are turned off and only the cursor image is displayed. 

85 Note that this would happen if one of the routines you call happens to call window get ( ) of 
WIN CURSOR. 
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Example 3: Turning on the Suppose you have a canvas window in which you want to turn on both the hor- 

Crosshairs izontal and vertical crosshairs. This can be done by getting the cursor from the 

window and setting the CURSOR_SHOW_CROSSHAlRS attribute: 


Cursor cursor; 

cursor = window_get (my_canvas , WINCURSOR) ; 
cursor_set( cursor, CURSOR_SHOW_CROSSHAIRS, TRUE, 0); 
windowset (my_canvas , WIN_CURSOR, cursor, 0); 

\ 



When the crosshairs are turned on, they are displayed according to the current 
value of their other attributes (e.g. thickness and drawing op). 

13.4. Some Cursor This section describes some of the cursor attributes in more detail. Note that for 

Attributes the crosshair attributes, you can control the individual crosshairs as well as both 

crosshairs by using the appropriate attribute. For example, you can set the length 
for both crosshairs with CURS0R__CR0SSHAIR_LENGTH or the length of only 
the horizontal crosshair with CURSOR_HORIZ_HAIR_LENGTH. 

cursorjmage The cursor image is the memory pixrect that is drawn on the screen as the mouse 

moves. Use the mpr static ( ) macro, as shown in Example 1, to create the 
memory pixrect. The image is represented as an array of 16 shorts, each of 
which represents a 16-pixel wide scan line. The scan lines are usually arranged 
in a single column, yielding a 16 x 16 pixel image. Other arrangements, such as 
32 pixels wide x 8 pixels deep, are also possible. The maximum size of a cursor 
in SunView 1 is 32 bytes; the minimum width is 16, the width of one scan line. 

cursor jotOT and cursor.yhot The “hot spot” defined by ( CURSOR XHOT, CURSOR_YHOT ) associates the 

cursor image, which has height and width, with the mouse position, which is a 
single point on the screen. The hot spot gives the mouse position an offset from 
the upper-left comer of the cursor image. For example, if the upper left comer of 
the cursor image is at location (50, 40) and the cursor hot spot has been set to (8, 
8), the reported mouse position will be at (58, 48). 

Most cursors have a hot spot whose position is obvious from the image shape: 
the tip of an arrow, the center of a bullseye, the center of a cross-hair. Cursors 
can also be used to give status feedback — an hourglass to indicate that the pro- 
gram is not responding to user input is a typical example. This type of cursor 
should have the hot spot located in the middle of its image so the user has a 
definite spot for pointing and does not have to guess where the hot spot is. 

cursor_op The value given for this attribute is the rasterop which will be used to paint the 

cursor. 86 PIX_SRC | PIX_DST is generally effective on light backgrounds — 
in text, for example — but invisible over solid black. PIX SRC ~ PIX DST 
is a reasonable compromise over many different backgrounds, although it does 
poorly over a gray pattern. 



86 Rasterops are described fully in the Pixrect Reference Manual. 
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cursor_fullscreen The cursor crosshairs can be clipped to either the cursor’s window or the entire 

screen. If you want the crosshairs to extend past the edge of the window, set 
CURSOR_FULLSCREEN to TRUE. 

cursor_crosshair_length If you don’t want the crosshairs to cover the entire window (or screen), you can 

set the length of both crosshairs with CURSOR CROSSHAIR LENGTH. The 
value of this attribute is actually half the total crosshair length. For example, if 
you want the crosshairs to be 400 pixels wide and high, set the 
CURSOR CROSSHAIR LENGTH to 200. You can restore the extend-to-edge 
length by giving a value of CURSOR_TO_EDGE for 
CURSOR_CROSSHAIR_LENGTH. 

cursor_crosshair_border_gravity If the crosshair border gravity is enabled, the crosshairs will "stick" to the edge of 

the window (or screen). This is only interesting if the 
CURSOR_CROSSHAIR_LENGTH is not set to CURSOR_TO_EDGE. With 
border gravity turned on, each half of each crosshair will be attached to the edge 
of the window. With the cursor image displayed, this feature might be useful to 
help the user line up the cursor to a grid drawn on the edges of the window. 

cursor_crosshair_gap If you don’t want the halves of each crosshair to touch, you can set the 

CURSOR_CROSSHAlR_GAP to the half-length of space to leave between each 
crosshair half. If you set CURSOR_CROSSHAlR_GAP to CURSOR_TO_EDGE, 
the crosshairs will back off to the edge of the CURSOR_lMAGE rectangle. 
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14 



Icons 



An icon is a small (usually 64 by 64 pixel) picture representing a base frame in 
its closed state. The icon is typically a picture indicating the function of the 
underlying application. 

Header Files The definitions necessary to use icons are found in the file 

<suntool/icon . h> , which is included by default when you include the file 
<suntool/sunview. h>. 

Summary Listing and Tables To give you a feeling for what you can do with icons, the following page lists the 

available icon attributes, functions and macros. Many of these are discussed in 
the rest of this chapter and elsewhere (use the Index to check). All are briefly 
described with their arguments in the menu summary tables in Chapter 19, Sun- 
View Interface Summary : 

o the Icon Attributes , 

□ the Icon Functions and Macros. 
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Icon Attributes 


ICON_FONT 


ICON_IMAGE_RECT 


ICON_WIDTH 


ICON_HEIGHT 


ICON_LABEL 




ICON_IMAGE 


ICON_LABEL_RECT 





Icon Functions and Attributes 


icon_create ( attributes ) 


icon_set ( icon , attributes ) 


icon_destroy( icon) 


DEFINE_ICON_FROM_IMAGE ( name , image ) 


icon_get ( icon , attribute ) 





14.1. Using Images You can create and edit images easily using the program iconedit(l). The 

Generated With output of iconedit is a file containing an array of shorts representing the 

iconedit image. In order to use the image in a program, you must first define a static 

memory pixrect containing this data. The mpr_static ( ) macro is provided 
for this purpose. 

The first argument to mpr_static ( ) is the name of the pixrect to be defined. 
Next come the width, height and depth of the image, typically 64, 64 and 1. The 
last argument is the array of shorts containing the bit pattern of the icon image. 

This macro will create a structure struct mpr data name _ data (that is, a 
structure of type mpr_data, whose name is the name specified in the macro 
appended with jla ta). Also a struct pixrect namejnvpr is created by 
appending _mpr to the specified name. The programmer is cautioned not use 
either of these names. 

For example: 



static short icon_image[] = { 

#include " f ile_generated_by_iconedit " 

} ; 

mprstatic ( icon_pixrect , 64, 64, 1, icon_image) ; 
v 



The statically defined image is passed in to icon create ( ) at run time: 



myicon = icon_create ( ICON_lMAGE, siconpixrect , 0); 

S. / 



Once you have created an icon, you can retrieve and modify its attributes with 
icon get ( ) and icon_set ( ) , and destroy it with icon_destroy ( ) . 

Instead of creating the icon dynamically with icon create ( ) , you can use 
the DEFINE_IC0N_FR0M_IMAGE ( ) macro to generate a static icon. 87 



87 



The structure generated is actually an extern. 
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static short icon_image[] = { 

# include " f ile_generated_by_iconedit " 

}; 

DEFINE_ICON_FROM_IMAGE ( icon, icon_image) ; 

s > 



This macro statically allocates a structure representing an icon. Note that you 
must pass the address of this structure — &icon in the example above — into 
icon_get ( ) , icon_set ( ) , and icon_destroy ( ) . 

Note that one of the cautions expressed earlier in conjunction with 

mpr static ( ) apply here, also. Do not use a name of the form icon-name- 

argument _data elsewhere in your program. 

WARNING The DEFINE ICON FROM IMAGE ( ) macro may not be supported in future 
releases. We recommend that you use icon create ( ) instead. 



14.2. Modifying the Icon’s It is often useful to change the icon’s image dynamically, rather than simply 
Image using the icon as a static placeholder. When mailtool receives new mail, for 

example, it lets the user know by modifying its icon to show a letter arrived in 
the mailbox, clocktool uses its icon to represent a moving clock face. 

The steps to follow in modifying an icon’s image are: 

□ get the frame’s icon (attribute FRAME_lCON); 

□ get the icon’s pixrect (attribute IC0N_IMAGE); 

□ modify the pixrect as desired, or substitute a new pixrect; 

□ give the pixrect with the new image back to the icon; 

□ give the new icon back to the frame. 

For example: 



modifyicon (frame ) ; 

Frame frame; 

Icon icon; 

Pixrect *pr; 

icon = (Icon) window_get( frame, FRAMEICON) ; 
pr = (Pixrect *) icon get ( icon, ICON_IMAGE) ; 

(modify pr) 

icon_set ( icon , ICON__IMAGE, pr, 0); 
window_set ( frame, FRAME_ICON, icon, 0); 

} 





#sun 

V microsystems 



Revision A, of March 27, 1990 







244 SunView Programmer’s Guide 



14.3. Loading Icon Images Often it is sufficient to define the image for a program’s icon at compile time, 

At Run Time with mpr_static ( ) . However, you may want to allow the user to create his 

own icon images, and give the names of the files containing the images to your 
program as command-line arguments. Then you can load the images from the 
files the user has specified. Routines to load icon images from files at run time 
are described in Chapter 11 of the SunView System Programmer’s Guide. 
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Scrollbars 



The canvas, text and panel subwindows have been designed to work with 
scrollbars. The text subwindow automatically creates its own vertical scrollbar. 
For canvases and panels, it is your responsibility to create the scrollbar and pass 
it in with the attributes WIN_VERTICAL_SCR0LLBAR or 
WIN_HORI Z ONT AL_S C ROLLB AR . 

Section 15.2, Scrollbar User Interface, describes how the user interacts with 
scrollbars. Basic scrollbar usage is covered in Section 15.3, Creating, Destroy- 
ing and Modifying Scrollbars , and programmatic scrolling is covered in Section 
15.4, Programmatic Scrolling. 

You may want to use scrollbars in an application not based on canvases, text 
subwindows or panels, in which case you must manage the interaction with the 
scrollbar directly. For an explanation of how to do this, see the Scrollbars 
chapter in the SunView System Programmer’s Guide. 

Header Files The definitions necessary to use scrollbars are found in the header file 

<suntool/scrollbar . h> 

Summary Listing and Tables To give you a feeling for what you can do with scrollbars, the following page 

contains a list of the available scrollbar attributes, functions and macros. Many 
of these are discussed in the rest of this chapter and elsewhere (use the Index to 
check). All are briefly described with their arguments in the scrollbar summary 
tables in Chapter 19, SunView Interface Summary: 

□ the Scrollbar Attributes, 

□ the Scrollbar Functions. 
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Scrollbar Attributes 



SCROLL_ABSOLUTE_CURSOR 

SCROLLACT IVE_CURSOR 

SCROLL_ADVANCED_MODE 

SCROLL_BACKWARD_CURSOR 

SCROLLBARCOLOR 

SCROLL_BAR_DISPLAY_LEVEL 

SCROLL_BORDER 

SCROLL_BUBBLE_COLOR 

SCROLL_BUBBLE_DISPLAY_LEVEL 

SCROLL_BUBBLE_MARGIN 

SCROLL_DI RECTI ON 

SCROLLENDPOINTAREA 

SCROLL_FORWARD_CURSOR 

SCROLL_GAP 

SCROLL_HEIGHT 

SCROLL_LAST_VIEW_START 

SCROLL_LEFT 

SCROLL_LINE_HEIGHT 

SCROLL_M ARG I N 

SCROLL MARK 



SCROLL_NOTIFY_CLIENT 

SCROLLNORMALIZE 

SCROLL_OBJECT 

SCROLL_OBJECT_LENGTH 

SCROLL_PAGE_BUTTONS 

SCROLL_PAGE_BUTTON_LENGTH 

SCROLL_PAI NT_BUTTONS_PROC 

SCROLL_PIXWIN 

SCROLLPLACEMENT 

SCROLL_RECT 

SCROLL_REPEAT_T IME 

SCROLL_REQUEST_MOTION 

SCROLL_REQUEST_OFFSET 

SCROLL_THICKNESS 

SCROLL_TO_GRID 

SCROLL_TOP 

SCROLL_VIEW_LENGTH 

SCROLL_VIEW_START 

SCROLL WIDTH 



Scrollbar Functions and Macros 

scrollbar_create ( attributes ) scrollbar_paint ( scrollbar ) 

scrollbar_destroy ( scrollbar ) scrollbar_paint_clear ( scrollbar ) 

scrollbar_get ( scrollbar , attribute ) scrollbar_clear_bubble ( scrollbar ) 

scrollbar_set ( scrollbar , attributes ) scrollbar_paint_bubble ( scrollbar ) 

scrollbar_scroll_to( scrollbar , new_view_start) 
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15.1. Scrolling Model Scrollbars allow the user to control which portion of an object is visible when the 

object is larger than the window it is displayed in. Within the scrollbar is a 
darker area called the bubble. The size and position of the bubble within the bar 
tell the user where he is in the object and how much of the object is visible. By 
moving the bubble within the bar, the user brings different portions of the object 
into view. 

The length of the object, the length of the visible portion of the object, and the 
offset of the visible portion within the object are given by the attributes 
SCROLL_OBJECT_LENGTH, SCROLL_VIEW_LENGTH, and 
SCROLL_VlEW_START. The relationship between these three view-space 
metrics is shown in the figure on the next page. 
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Figure 15-1 Scrolling Model 
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Figure 15-1 shows a two-page document being viewed within a window roughly 
half the size of the document. The three view-space attributes 
SCROLL_OBJECT_LENGTH, SCROLL_VIEW_LENGTH, and 
S CR0LL_VI EW_ST ART are shown superimposed on the document. Note the 
relative size and position of the bubble within the scrollbar — it is roughly half 
the size of the window and positioned near the bottom. 
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15.2. Scrollbar User 
Interface 

Types of Scrolling Motion The default scrollbar is vertical, with page buttons at the top and bottom. To 

scroll, the user moves the cursor into the scrollbar (either the bar itself or one of 
the page buttons) and clicks one of the mouse buttons. The following table 
describes the available scrolling actions and how they are generated: 

Table 15-1 Scrolling Motions 



Mouse Button 


Cursor Location 


Scrolling Action 


LEFT 


page button 


Line forward 


RIGHT 


page button 


Line backward 


MIDDLE 


page button 


Page forward 


MIDDLE (shifted) 


page button 


Page backward 


LEFT 


bar 


Line opposite cursor goes to top 


RIGHT 


bar 


Top line comes to cursor 


LEFT (shifted) 


bar 


Bottom line comes to cursor 


RIGHT (shifted) 


bar 


Line opposite cursor goes to bottom 


MIDDLE 


bar 


The line whose offset into the 
scrolling object approximates that 
of the cursor into the scrollbar is 
positioned at top (“thumbing”). 



Holding the button down within the scrollbar causes the cursor to change, pre- 
viewing the scrolling action for that button. Releasing the button causes the 
scrolling action to be performed, or, if the user holds down the mouse button, the 
scrolling motion will start in repeating mode. 

Undoing a Scroll I Shift 1 -MIDDLE mouse button positions the viewing window to the most recent 

position which was left by an absolute motion (thumbing or undoing). The undo- 
ing position is initialized to the beginning of the scrollable object. 
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15.3. Creating, Destroying Scrollbars are created and destroyed with scrollbar_create ( ) and 

and Modifying scrollbar_destroy ( ) . To take the simplest possible example, you get a 

Scrollbars default scrollbar (vertical, on the left edge of the subwindow, etc.) by calling: 



— 


. 


Scrollbar bar; 




bar = scrollbar_create(0) ; 




l 


J 



You would destroy the scrollbar with the call: 



— 




scrollbar_destroy(bar ) ; 




\ 


J 



The appearance and behavior of a given scrollbar is determined by the values of 
its attributes. Here’s an example of a non-default scrollbar: 





bar_l = scrollbar_create ( 




"N 




SCROLL PLACEMENT, 


SCROLL EAST, 






SCROLL_BUBBLE_COLOR , 


SCROLL_BLACK , 






SCROLL BAR DISPLAY LEVEL, 


SCROLL ACTIVE, 






SCROLL_BUBBLE_DISPLAY_LEVEL, 


SCROLL_ACTIVE , 






SCROLL DIRECTION, 


SCROLL VERTICAL, 






SCROLL_THICKNESS, 


NJ 

O 






SCROLL BUBBLE MARGIN, 


4, 






0), 












J 



In the above call, setting SCROLL_PLACEMENT to SCROLL_EAST will cause 
the scrollbar to appear on the right edge of the subwindow. The scrollbar will be 
20 pixels wide with a black bubble 4 pixels from each edge of the bar. The bar 
and bubble will be shown only when the cursor is in the scrollbar. 

You can modify and retrieve the attributes of a scrollbar with the two routines: 

scrollbar_set ( scrollbar , attributes ) 

Scrollbar scrollbar; 

<attribute-list> attributes; 

caddrt 

scrollbarget ( scrollbar , attribute ) 

Scrollbar scrollbar; 

Scrollbar_attribute attributes; 

If the scrollbar parameter is NULL, scrollbar_get ( ) returns 0. Note 
that the return value should always be cast to the type of the expected attribute. 

SCROLL_RECT, SCROLL_THICKNESS, SCROLLJHEIGHT and 
SCROLL_wiDTH do not have valid values until the scrollbar is passed into the 
subwindow. As a work-around for this problem, the special symbol 
SCROLLBAR has been provided. You can determine the default thickness of a 
scrollbar before it has been attached to a subwindow with the call: 
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thickness = (int) scrollbar_get (SCROLLBAR, SCROLL_THICKNESS ) ; 

v. J 



This convention is currently only implemented for SCROLL THICKNESS. 

If you set the SCROLL_THlCKNESS attribute then you must also set the 
S CROLL_DI RECT ION of the scrollbar, since the dimension of the scrollbar that 
is altered by SCROLL THICKNESS depends on the orientation of the scrollbar. 

The figures on the next page show some of the attributes controlling the visual 
appearance of a scrollbar. 88 Figure 15-2 illustrates the attributes that control the 
scrollbar appearance. Figure 15-3 illustrates the attributes that control the 
scrollbar placement. 



88 For a complete list of the scrollbar attributes see the Scrollbar Attributes table in Chapter 19, SunView 
Interface Summary. 
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Figure 15-2 Attributes Controlling Scrollbar Appearance 



Scrollbar Attributes: 



SCROLL_RIGHT 

SCROLL_THICKNESS 

SCROLl_BAR_COLOR 

■ SCROLL_BLACK 
□ SCROLL_WHITE 






Page Button Attributes 
SCROLL_PAGE_BUTTONS: TRUE or FALSE 
SCROLL_PAGE_BUTTON_LENGTH 



Bubble Attributes: 
SCROLL_BUBBLE_MARGIN 
SCR0LL_BUBBLE_C0L0R 

H SCROU BLACK 

H SCROLL.GREY 



Figure 15-3 Scrollbar Placement Attributes 



SCROLL_DIRECTION : 

SCROLL VERTICAL SCROLL HORIZONTAL 
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15.4. Programmatic 
Scrolling 



SCROLLJVORMALIZE 

attribute 



To scroll to a given location from your program, call: 

scrollbar_scroll_to( scrollbar, new_view_start) 

Scrollbar scrollbar; 
long new_view_start; 

This routine saves the current value of SCROLL_VIEW_START as 
SCROLL_LAST_VIEW_START, sets SCROLL_VIEW_START to the value 
passed in as new_view_start, and posts a scroll event to the scrollbar’s 
client (i.e. the canvas, panel or text subwindow) using the Notifier. This has the 
same effect as if the user had requested a scroll to new_view_start. 

The default for SCROLL_NORMALlZE is TRUE. When scrollbars are used 
within panels, the default behavior is to scroll to the first line in view for a panel 
item. This can sometimes cause problems when trying to view a panel item, such 
as a choice item layed out vertically, since all PANEL_CHOlCE_STRINGS 
may not be visible within the scroll region and cannot be scrolled into view 
because SCROLL_NORMALiZE is true. In those instances set 
SCROLL_NORMALlZE to FALSE, in addition to setting the scrollbar’s 
SCROLL_line_height. For example: 
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# include <suntool/sunview.h> 

# include <suntool/panel .h> 

# include <suntool/scrollbar .h> 

Frame frame; 

Panel panel; 

Panel_item choice_item; 
static int choice_count = 0; 

Scrollbar sb; 
main(argc,argv) 
int argc ; 

char **argv; 

{ 

frame = window_create ( NULL , FRAME , 

0 ); 

sb = scrollbar_create(SCROLL_NORMALIZE, FALSE, 
SCROLL_LINE_HEIGHT , 5, 

0 ), 

panel = window_create( frame, PANEL, 

WIN_R0WS, 5, 

WIN_VERTICAL_SCROLLBAR, sb, 

0 ); 

choice_item = panel_crea te_item( panel, PANEL_CHOICE, 
PANE L_L AB E L_S TR I NG , " Choices : " , 

PANEL_LAYOUT , PANEL_VERTICAL , 

PANEL_CHOICE_STRINGS , 



"01" , 


"02" , 


"03 


" 04 " , 


"05", 


"06 


"07" , 


"08" , 


"09 


"10", 


"11", 


"12 


"13" , 


"14", 


"15 


0, 






0); 







window_f it_height( frame) ; 
window_ma in_loop ( frame ) ; 

I 
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The Selection Service 



The Selection Service provides for flexible communication among window appli- 
cations. You can use the Selection Service to query and manipulate the selec- 
tions the user has made. 

This chapter gives only the simplest example of using the Selection Service. To 
find out more about the Selection Service and the other functionality it provides, 
refer to Chapter 9 of the SunView System Programmer's Guide. 

The definitions necessary to use the Selection Service are found in the include 
file <suntool/seln . h> . 
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16.1. Getting the Primary The primary selection is the selection made by the user without holding down 
Selection any of the function keys, and is indicated with reverse-video highlighting on the 

screen. 

The routine below is taken from the program filer, listed in Appendix A. It 
retrieves the primary selection by first asking the Selection Service which win- 
dow has the primary selection, then asking that window for the characters that 
are in the selection, saving them in a static buffer, and returning a pointer to that 
buffer: 

' V 

^define <suntool/seln . h> 

#def ine MAX_F I LENAME_LEN 256 
char * 

getselection ( ) 

{ 

static char f ilename [MAX_FILENAME_LEN] ; 

Seln_holder holder; 

Seln_request ^buffer; 

holder = seln_inquire(SELN_PRIMARY) ; 

buffer = seln_ask ( &holder , SELN_REQ_CONTENTS_ASCII , 0, 0); 
strncpy (filename, 

buffer->data + sizeof (Seln_attribute) , 

MAX_F ILENAME_LEN ) ; 

return (filename); 

1 

k 



This example has been kept simple by removing error checking. The code relies 
on the fact that if there is no primary selection, or the Selection Service process is 
not running, or the holder of the primary selection failed to returned the selection 
string, then the buffer returned by seln ask ( ) will have an empty string for 
the selection characters. 

The routine also assumes that the selection will be no more than 256 characters 
long. seln_ask ( ) will handle selections of up to about 2000 characters. To 
find out how to handle arbitrarily large selections, or selections other than the pri- 
mary selection, refer to the SunView System Programmer's Guide . 



16.2. Setting the Primary 
Selection 



For an example of a program which sets, and responds to queries about, the 
selection, see seln demo, in Chapter 9 of the SunView System Programmer’s 
Guide. 
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The Notifier 



The Notifier is a general-purpose mechanism for distributing events to a collec- 
tion of clients within a process. It deteas events in which its clients have 
expressed an interest, and dispatches these events to the proper clients, queuing 
client processing so that clients respond to events in a prediaable order. 

An overview of the notification-based model is given in Chapter 2, The SunView 
Model. 

To encourage the porting of existing applications, the Notifier has provisions to 
allow programs to run in the Notifier environment without inverting their control 
structure. See Section 17.6, Porting Programs to SunView. 

Header Files The definitions for the Notifier are contained in the file 

<sunwindow/notify . h>, which will be included indirectly when you 
include <suntool/sunview .h>. 89 

Related Documentation This chapter will suffice for the majority of SunView applications. See the 

chapters titled Advanced Notifier Usage and The Agent and Tiles in the SunView 
System Programmer’s Guide for more information on the Notifier and 
SunView ’s usage of it. When looking up Notifier-related information, look first 
in the index to this book, then in the index to the SunView System Programmer’s 
Guide. 

Summary Listing and Table To give you a feeling for what you can do with the Notifier, the following page 

contains a list of the available Notifier funaions. Many of these are discussed in 
the rest of this chapter and elsewhere (use the Index to check). All are briefly 
described with their arguments in the Notifier Functions table in Chapter 19, Sun- 
View Interface Summary. 



89 For those programmers utilizing the Notifier outside of SunView (a perfectly reasonable thing to do), the 
code that implements the Notifier is found in /usr/lib/1 ibsunwindow . a. 
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Notifier Functions 

notify_default_wait3 (client, pid, status, rusage) 
notify_dispatch( ) 
notify_do_dispatch( ) 

notify_interpose_destroy_func( client, destroy_func) 
notify_interpose_event_func( client, event_func, type) 
notify_itimer_value( client, which, value) 
notify_next_destroy_func( client, status ) 
notify_no_dispatch( ) 
noti f y_perror ( s ) 

not i f y_set_de s troy_f unc ( client , des troy_f unc ) 
notify_set_exception_func( client, exception_func, fd) 
notify_set_input_func( client, input_func, fd) 

notify_set_itimer_func (client, itimer_func, which, value, ovalue) 
notify_set_signal_func( client, signal_func, signal, when) 
notify_start( ) 
notify_stop( ) 

notify_set_output_func( client, output_func, fd) 
notify_set_wait3_func(client, wait3_func, pid) 
notify_veto_destroy( client) 
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17.1. When to Use the 
Notifier 



17.2. Restrictions 



Don’t Call. . . 

signal(3) 

sigvec(2) 

setitimer(2) 

alarm(3) 

getitimer(2) 

wait3(2) 



Since the Notifier is used by the SunView libraries, any program that uses Sun- 
View implicitly uses the Notifier. You will have to use the Notifier explicitly if 
you want to do any of the following: 

□ Catch signals, e.g., SIGCONT. 

□ Notice state changes in processes that your process has spawned, e.g., a child 
process has died. 

□ Read and write through file descriptors, e.g., using pipes. 

□ Receive notification of the expiration of an interval timer, e.g., so that you 
can provide some blinking user feedback. 

□ Extend, modify or monitor SunView Notifier clients, e.g., noticing when a 
frame is opened, closed or about to be destroyed. 

□ Use a non-notification-based control structure while running under Sun- 
View, e.g., porting programs to SunView. 

The Notifier imposes some restrictions on its clients which designers should be 
aware of when developing software to work in the Notifier environment. These 
restrictions exist so that the application and the Notifier don't interfere with each 
other. More precisely, since the Notifier is multiplexing access to user process 
resources, the application needs to respect this effort so as not to violate the shar- 
ing mechanism. 

Assuming an environment with multiple clients with an unknown notifier usage 
pattern, you should not use any of the following system calls or C library rou- 
tines: 90 

The Notifier is catching signals on the behalf of its clients. If you set up your 
own signal handler over the one that the Notifier has set up then the Notifier will 
never notice the signal. 

The same applies for sigvec(2) as does for signal(3), above. 

The Notifier is managing two of the process’s interval timers on the behalf of its 
many clients. If you access an interval timer directly, the Notifier could miss a 
timeout. Use notify_set_itimer_f unc ( ) instead of setitimer(2). 

Because alarm(3) sets the process's interval timer directly, the same applies for 
alarm(3) as does for setitimer(2), above. 

When using a notifier-managed interval timer, you should call 

notif y_itimer_value ( ) to get its current status. Otherwise, you can get 

inaccurate results. 

The Notifier notices child process state changes on behalf of its clients. If you do 
your own wait 3 (2), then die notifier may never notice the change in a child 



90 A future release may provide modified versions of some of these forbidden routines that will allow their 
use without restriction. However, the restrictions described in Don’t Catch . . ., below, will continue to be 
germane. A s ignal ( ) Replacement for Notifier Compatibility, in Section 17.4, provides a code patch for 
programs that catch signals. 
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wait(2) 

ioctl(2) (..., FIONBIO, ...) 
ioctl(2) (..., FIOASYNC, ...) 

system(3) 



Don’t Catch... 

SIGALRM 

SIGVTALRM 

SIGTERM 

SIGCHLD 

SIGIO 

SIGURG 



process or you may get a change of state for a child process in which you have no 
interest. Use notify_set_wait3_func{ ) instead of wait 3 (2). 

The same applies for wait(2) as does for wait3(2), above. 

This call sets the blocking status of a file descriptor. The Notifier needs to know 
the blocking status of a file descriptor in order to determine if there is activity on 
it. f cntl(2) has an analogous request that should be used instead of ioctl(2). 

This call controls a file descriptor's asynchronous io mode setting. The Notifier 
needs to know this mode in order to determine if there is activity on it. 
f cntl(2) has an analogous request that should be used instead of ioctl(2). 

In the SunOS, this function calls signal(3) and wait(2). Hence you should 
avoid using this for the reasons mentioned above. Calls to system(3) should be 

replaced with something like the following. 
. 

if((pid = vfork()) == 0) { 

(void) execl ( "/bin/sh" , "sh", "-c", str, (char *)0); 
_exit (127 ) ; 

] 

notify_set_wait3_func (me, my_handler, pid) ; 

l > 



Clients should not have to catch any of the following signals. If you are, then 
you are probably also making one of the forbidden calls described above. You 
might also be utilizing the Notifier inappropriately if you think that you have to 
catch any of these signals. The Notifier catches these signals itself under a 
variety of circumstances: 

Caught by the Notifier’ s interval timer manager. Use 
notify_set_itimer_func( ) instead. 

The same applies for SIGVTALRM as does for SIGALRM above. 

Caught by the Notifier so that it can tell its clients that the process is going away. 
Use notify_set_destroy_f unc( ) if that is why you are catching 
SIGTERM. 

Caught by the Notifier so that it can do child process management. Use 
notif y_set_wait3_f unc ( ) instead. 

Caught by the Notifier so that it can manage its file descriptors that are running in 
asynchronous io mode. Use notif y_set_input_func ( ) 91 or 
notif y_set_output_f unc ( ) if you want to know when there is activity 
on your file descriptor. 

Caught by the Notifier so that it can dispatch exception activity on a file descrip- 
tor to its clients. Use notify_set_exception_f unc ( ) if you are looking 
for out-of-band communications when using a socket. 



91 Do not use a NULL client handle when you use notif y_set_input_f unc ( ) or the Notifier will go 
into an infinite loop. 
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If you think you have to catch one of these signals, then be sure to use 
notif y_set_signal_func ( ). 



17.3. Overview 

How the Notifier Works Before it can receive events, a client must advise the Notifier of the types of 

events in which it is interested. It does this by registering an event handler func- 
tion (which it must supply) for each type of event in which it is interested. When 
an event occurs, the Notifier calls the event handler appropriate to the type of 
event. 

Figure 17-1 shows an overview of how the notification mechanism works. 



Figure 17-1 Overview of No tifica tion 




— -> Client registers event proc at initialization time 
> Notifier calls back to client when event received 



Client Handles The Notifier uses a client handle as the unique identifier for a given client. The 

Notifier, without interpreting the client handle in any way, uses it to associate 
each event with the event handler for a given client. 

The only requirement for a client handle is that it must be unique (within a pro- 
cess). Since a program text address or the address of an allocated data block are 
guaranteed to be unique, they can be used. Since stack addresses are not in gen- 
eral guaranteed to be unique they should not be used. Internally, SunView uses 
the object handles returned from window create ( ) as notifier client handles. 

Types of Interaction Client interaction with the Notifier falls into the following functional areas: 

□ Event handling — A client may receive events and respond to them via 
event handlers. Event handlers do the bulk of the work in the Notifier 
environment. The various types of events are in Section 17.4, Event Han- 
dling. 

□ Interposition — A client may request that the Notifier install a special type 
of event handler (supplied by the client) to be inserted (or interposed ) ahead 
of the current event handler for a given type of event and client. This allows 
clients to screen incoming events and redirect them, and to monitor and 
change the status of other clients. Examples of interposition may be found 
below under Monitoring a Frame's State. 
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□ Notifier control — A client may exercise control over when dispatching of 
events occurs. See Section 17.6, Porting Programs to SunView. 

17.4. Event Handling This section describes how to be notified of UNIX-related events and notifier sup- 

ported destroy events (see Chapter 6, Handling Input, for a description of 
SunView-defined events). UNIX events are low-level occurrences that are mean- 
ingful at the level of the operating system. These include signals (software inter- 
rupts), input pending on a file descriptor, output completed on a file descriptor, 
tasks associated with managing child processes, and tasks associated with 
managing interval timers. 

A client establishes an interest in a certain type of event by registering an event 
handler procedure to respond to it. The event handler for a given type of event 
has a mandatory calling sequence, as described below. All event handlers return 
a value of either NOTI F Y_DONE or NOTlFY_lGNORED depending on whether 
the event was acted on in some way or failed to provoke any action, respectively. 

When registering an event handler, the registration procedure returns a pointer to 
the function that was in place previous to the current call. On initialization, the 
Notifier sets up its internal tables by registering “dummy'” functions as place- 
holders. These dummy functions are no-op functions with no harmful side- 
effects. The first time a client registers a given type of event handler, it will 
receive a pointer to a “dummy” function. 

The following sections describe common usages of various types of events. 

Child Process Control Events Let’s say that you want to fork a process to perform some processing on your 

behalf. UNIX requires that you perform some housekeeping of that process. The 
minimum housekeeping required is to notice when that process dies and “reap” 
it. You can register a wait3 event handler, 92 which the Notifier will call when- 
ever a child process changes state (e.g. dies), by calling: 

Notify_func 

noti fy_set_wa it 3__f unc ( client, wait3_func, pid) 

Notif y__client client; 

Notify_func wait3_func; 

int pid; 



“Reaping” Dead Processes Clients using child process control which simply need to perform the required 

reaping after a child process dies can use the predefined 

notif y def ault_wait3 ( ) as their wait3 event handler. For example: 



92 The name wait3 event originates from the wait 3(2) system call. 




microsystems 



Revision A, of March 27, 1 990 





Chapter 17 — The Notifier 263 



Results from a Process 





#include <sunwindow/notify . h> 

static int my_client_object ; 

static Notify_client me = &my_client_object ; 

int pid; 

if ((pid = my_fork())) 

(void) notify_set_wait3_f unc (me, not if y_def ault_wait3 , 

pid) ; 

/* Start dispatching events */ 

(void) notify_start ( ) ; 

\ J 



This is sufficient to have your child process reaped on its death. The Notifier 
automatically removes a dead process’s wait3 event handler from its internal data 
structures. 

NOTE The use of me as a client handle is arbitrary, but illustrates one method of gen- 

erating a unique client handle. 

A more interesting application might actually receive some results from the pro- 
cess it forked. In this case, the application would supply its own wait3 event 
handler 93 . For example: 



#include <sunwindow/notify . h> 

#include <sys/wait.h> 

#include <sys/time.h> 

#include <sys/resource . h> 

static Notify_value my_wait3_handler ( ) ; 

/* Register a wait3 event handler */ 

(void) notify_set_wait3_func(me, my_wait3__handler , pid); 

/* Start dispatching events */ 

(void) notif y_start ( ) ; 

static Notify_value 

my_wait3_handler (me, pid, status, rusage) 

Notif y_cl ient me; 
int pid; 

union wait *status; 
struct rusage *rusage; 

if ( WIFEXITED ( *status ) ) { 

/* Child process exited with return code */ 
my _return_code_handler (me, status->w_retcode) ; 

/* Tell the notifier that you handled this event */ 
return (NOTIFY_DONE) ; 

} 

/* Tell the notifier that you ignored this event */ 
return ( NOT IFY_IGNORED ) ; 





93 See the wait(2) manual page for details of union wait and struct rusage. 
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Input-Pending Events (pipes) A program may need to know when there is input pending on a file descriptor — 

for instance, on one end of a pipe. Let’s extend our previous example a bit to 
include reading data from a pipe connected to a process that we have forked. 

You can register an input-pending event handler which the Notifier will call 
whenever there is input pending on a file descriptor 94 by calling: 

Notify_func 

notify_set_input_func( client, input_func, fd) 

Notify_client client; 

Notify_func input_func; 

int fd; 

The calling sequence for the input_f unc ( ) you supply is as follows: 

Notify_value 
input_func( client, fd) 

Notify_client client; 
int fd; 



Example: Reading a Pipe 



\ 

#include <sunwindow/notify . h> 

static Notify_value my_pipe_reader ( ) ; 

int f ildes [ 2 ] ; 

/* Create a pipe */ 
if (pipe(f ildes) == -1) { 
perror ( "pipe" ) ; 
exit ( 1 ) ; 

} 

/* Register an input-pending event handler */ 

(void) not if y_set input _f unc (me, my_pipe_reader , fildesfO]); 

... do fork and dispatching from wait 3 event example ... 

static Notifyvalue 
my_pipe_reader (me, fd) 

Notify client me; 
int fd; 

/* Read the pipe (fd) */ 

/* Tell the notifier that the input event is handled */ 
return (NOTIFY_DONE) ; 

V 



In the above example, the application uses the Notifier to read from the pipe 
because it doesn’t want to block on input pending on the pipe. In the case of a 
Sun View program, the program wants to return back to the Notifier ’s central 
dispatching loop so that the user can interact with the window while waiting for 
input to become available on the pipe. 



94 The file descriptor can be in blocking or non-blocking mode, or in asynchronous mode; the Notifier 
handles both as long as you have used f cnt 1(2) to set the modes. 
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When you close any file descriptor that has been registered with the Notifier you 
should unregister it. To do this, call notif y_set_input_f unc ( ) with a 
notif y_f unc of NOTIF Y_FUNC_NULL. 95 

Signals are UNIX software interrupts. The Notifier multiplexes access to the 
UNIX signal mechanism. A client may ask to be notified that a UNIX signal 
occurred either when it is received (asynchronously) and/or later during normal 
processing (synchronously). 

Clients may define and register a signal event handler to respond to any UNIX 
signal desired. However, many of the signals that you might catch in a tradi- 
tional UNIX program may be being caught for you by the Notifier (see Don’t 
catch above). 

CAUTION Clients of the Notifier must not directly catch any UNIX signals using s ig - 
nal(3) or sigvec(2). Regardless of whether clients choose synchronous or 
asynchronous signal notification, they must use the signal event mechanism 
described in this section. See Section 17.2, Restrictions . 

You can register a signal event handler which the Notifier will call whenever a 
signal has been caught by calling: 

Notify_f unc 

notify_set_signal_f unc ( client, signal_func, signal, when) 
Notify_client client; 

Notif y_f unc signal_func; 

int signal; 

Notify_signal_mode when; 

when can be either NOTIFY_SYNC or N0TIFY_ASYNC. NOTlFY_SYNC 
causes notification during normal processing, that is, the delivering of the signal 
is delayed, so that your program doesn’t receive it at an arbitrary time. 
N0TIFY_AS YNC causes notification immediately as the signal is received, — 
this mode mimics the UNIX signal(3) semantics. 

You should rewrite applications to use notify_set_signal_f unc ( ) . 
However, the Notifier routine notif y_set_signal_f unc ( ) does not fully 
emulate the signal(3) function. It does not handle errors the same way sig- 
nal(3) does. Errors from signal(3) are indicated by a -1 return value, and 
the value of err no is set to EINVAL. 



The errors for notif y set signal f unc ( ) are not communicated back to 
the caller, but error messages are printed. For example, if the signal number is 
not valid, the Notifier prints 



— 
Bad signal number 


a 


V 


J 



but its return value indicates success; the signal(3) system call does not print a 
message, but returns - 1 and sets errno to EINVAL. As another example, if 



A signal ( ) Replacement for 
Notifier Compatibility 



Closing the Pipe 



Signal Events 



95 This method of passing in a NOTIFY FUNC NULL to unregister an event handler from the Notifier 
works for any type of event. 
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SIGKILL or SIGSTOP are ignored or a handler supplied, the Notifier prints 




but its return value indicates success, while signal(3) does not print a message, 
returns value of -1, and sets err no to EINVAL. 



The work-around is to use the following replacement function for the C library 
version of sign a 1(3). This code converts signal ( ) calls into 
notif y_set_signal_func ( ) calls. Explicitly loading this code will over- 
ride the loading of the C library’s version of signal ( ) . This approach works 
only if all the signal handlers registered by signal ( ) only look at the first 
argument passed to them when a signal is received. Also, no Notifier client han- 
dle may be a small integer. 




Example: Writing to a Pipe Let’s extend our on-going example by writing on the pipe. Writing to a pipe that 

has no process at the other end to receive the message causes a SIGPIPE to be 
generated by UNIX. By default, an uncaught SIGPIPE causes a premature pro- 
cess termination. So, we are going to catch SIGPIPE so that our process 
doesn’t get killed if we start a process that dies. 8 



8 We are glossing over the part about actually writing to the pipe. If we wanted to write something to the 
pipe and then get some notification about when the write had actually completed (i.e., the other process had read 
it) we would use the not if y_set output func () call. The calling sequences for this routine and its 
event handler are exactly the same as those for not i f y_set_input _f unc ( ) (previously described). 
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#include <sunwindow/notif y . h> 

^include <signal.h> 

static Notify_value my_sigpipe_handler ( ) ; 

... do pipe from input-pending example ... 

... do notify set input f unc from input-pending example ... 

... do fork from wait3 event example ... 

/* Register a signal event handler */ 

(void) notify _set_signal func (me, my_sigpipe_handler , 

SIGPIPE, NOTIFYASYNC) ; 

/* Write a message on the pipe */ 



/* Start dispatching events */ 

(void) notif ystart ( ) ; 

static Notify_value 

my_sigpipe_handler (me, signal, when) 

Notif y_cl ient me; 

int signal; 

Not if y_signal_mode when; 

/* 

* This is a no-op function meant only to prevent us from 

* being killed because we didn't have a SIGPIPE handler. 

*/ 

return (NOTIFY_IGNORED) ; 

^ ) 



This example wouldn’t actually show my_sigpipe_handler ( ) being called 
unless you set up the child process to die right away. 

Asynchronous Event Handling An asynchronous signal notification can come at any time (unless blocked using 

sigblock(2)). This means that the client can be executing code at any arbi- 
trary place. Great care must be exercised during asynchronous processing. 

It is rarely safe to do much of anything in response to an asynchronous signal. 
Unless your program has taken steps to protect its data from asynchronous 
access, the only safe thing to do is to set a flag indicating that the signal has been 
received. 

When in an asynchronous signal event handler, the signal context and signal code 
is available from the follow routines: 

int 

notify_get_signal_code ( ) 

struct sigcontext * 
notify_get_signal_context ( ) 

The return values of these routines are undefined if called from a synchronous 
signal event handler. 



<®sun 

mirror vstpms 



Revision A, of March 27, 1990 






268 SunView Programmer’s Guide 



Timeout Events 



A client may require notification of an expired timer based on real time (approxi- 
mate elapsed wall clock time; ITIMER_REAL) or on process virtual time (CPU 
time used by this process; ITIMER_VIRTUAL). To receive this type of 
notification, the client must define and register a timeout event handler. 



Notify_func 

notify_set_itimer_func( client, itimer_func, which, value, 

ovalue) 

Notify_client client; 

Notify_func itimer_func; 

int which; 

struct itimerval *value, *ovalue; 



The semantics of which, value and ovalue parallel the arguments to seti- 
timer(2) (see the getitimer(2) manual page), which is either 
ITIMER REAL or ITIMER VIRTUAL. 



Example: Periodic Feedback As an example, we want to provide some form of blinking feedback. We do this 

by setting up an interval timer when we want to blink. We turn the internal timer 
off when we no longer need the blinking. 97 



97 This code segment should be wrapped in, say, a panel notify procedure, in order to be actually run. 
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#include <sunwindow/not ify . h> 

#include <sys/time.h> 

static int blinkingrequired; /* blinking desired */ 
static int blinking; /* blinking enabled */ 

#define ITIMER_NULL ((struct itimerval *)0) 
static Notify_value my _bl inker () ; 

if (blinking_required && Iblinking) { 

struct itimerval blink_timer; 

/* Set up interval with which to RELOAD the timer */ 
bl ink_timer . it_interval . tvusec = 0; 
blink_timer . it_interval . tv_sec = 1; 

/* Set up INITIAL value with which to SET the timer */ 
blink_timer . it_value . tv_usec = 0; 
blink_timer . it_value . tv_sec = 1; 

/* Turn on interval timer for client */ 

(void) notify_set_it imer_f unc (me , my_blinker, 
ITIMER_REAL, &blink_t imer , ITIMER_NULL) ; 
blinking = 1; 

1 else if ( !blinking_required && blinking) { 

/* Turn off interval timer for client */ 

(void) notify_set_itimer_f unc (me, my_blinker, 
ITIMER_REAL, ITIMER_NULL, ITIMER_NULL) ; 
blinking = 0; 

1 

static Notify_value 
my_blinker (me , which) 

Notify_client me; 
int which; 

/* Do the blink */ 

return ( NOTIFY_DONE ) ; 

v ) 



Polling Interval timers can be used to set up a polling situation. There is a special 

value argument to notif y_set_itimer_f unc ( ) that tells the Notifier to 
call you as often and as quickly as possible. This value is the address of the 
following constant: 

struct itimerval NOTIFY_POLLING_ITIMER; /*{ {0, 1} , {0, 1} }*/ 

This high speed polling can consume all of your machine’s available CPU time, 
but may be appropriate for high speed animation. It is used in the program 
spheres, which shows one way to convert and old SunWindows gfx subwindow- 
based program to SunView. spheres is explained in Appendix C, Converting 
SunWindows Programs to SunView, and is listed in full in in Appendix A, Exam- 
ple Programs. 
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Checking the Interval Timer The following function checks on the state of an interval timer by returning its 

current state in the structure pointed to by value. 

Notify_error 

notify_itimer_value ( client, which, value) 

Notify_client client; 

int which; 

struct itimerval * value; 



Turning the Interval Timer Off If you specify an interval timer with its it interval structure set to 

{0, 0 } , the Notifier flushes any knowledge of the interval timer after it delivers 
the timeout notification. Otherwise, supplying a NULL interval timer pointer to 
notify_set_itimer_func( ) will turn the timer off. 



17.5. Interposition SunView window objects utilize the Notifier for much of their communication 

and cooperation. The Notifier provides a mechanism called interposition, with 
which you can intercept control of the internal communications within SunView. 
Interposition is a powerful way to both monitor and modify window behavior in 
ways that extend the functionality of a window object. 

Interposition allows a client to intercept an event before it reaches the base event 
handler. The base event handler is the one set originally by a client. The client 
can call the base event handler before or after its own handling of the event, or 
not at all. Clients may use interposition to monitor and filter events coming in to 
an event handler and/or to modify a series of actions based on the results of some 
calculation. 

How Interposition Works A client requests that the Notifier install an interposer function, supplied by the 

client, for a specified client and type of event. When an event arrives, the 
Notifier calls the function at the top of the wait list for that client and that type of 
event. An interposed routine may (indirectly) call the next function in the inter- 
position sequence and receive its results. 

Figure 17-2 illustrates the flow of control with interposition. Note that the inter- 
poser could have stopped the flow of control to the base event handler. 
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Figure 17-2 



Flow of Control in Interposition 




Monitoring a Frame’s State You can notice when a frame opens or closes by interposing in front of the 

frame’s client event handler. The client event handler is a Sun View specific 
event handler which is built on top of the Notifier’ s general client event mechan- 
ism. 98 To install an interposer call the following routine: 

Notify_error 

notify_interpose_event_func( client, event_func, type) 
Notify_client client; 

Notify_func event_func; 

Notify_event_type type; 

client must be the handle of the Notifier client in front of which you are inter- 
posing. In SunView, this is the handle returned from window_create ( ) ." 
type is always N0TIFY_SAFE for SunView clients. 

Example: Interposing on Let’s say that the application is displaying some animation, and wants to do the 

Open/Close necessary computation only when the frame is open. It can use interposition to 

notice when the frame opens or closes. 

The program spheres (which shows one way to convert an old SunWindows gfx 
subwindow-based program to SunView) uses this technique to stop shading an 
image when its frame is closed. It is explained in Appendix C, Converting 
SunWindows Programs to SunView, and is listed in full in in Appendix A, Exam- 
ple Programs. 

Another example appears on the following page. Note the the call to 
notif y_next_event_f unc ( ) , which transfers control to the frame’s client 
event handler through the Notifier. notif y_next_event_f unc ( ) takes the 
same arguments as the interposer. 



98 The stream of events sent to a client event handler is described in in Chapter 6, Handling Input. 

99 It could also be the handle returned from the call to scrollbar create ( ). 
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#include <suntool/sunview . h> 



static Notif y__value my_f rame_interposer ( ) ; 



Frame frame; 

/* Create the frame */ 

frame = window create(0, FRAME, 



/* Interpose in front of the frame's event handler */ 
(void) notif y_interpose_event_f unc ( frame, 

my_f rame_interposer , NOTIFY_SAFE ) ; 
/* Show frame and start dispatching events */ 
window_ma in_loop (frame) ; 

static Notify_value 

my_f rame_interposer ( frame , event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

int closedinit ial , closed_current ; 

Notify_value value; 

{ 

/* Determine initial state of frame */ 

closed_initial = (int) window_get ( frame , FRAME_CLOSED) ; 

/* Let frame operate on the event */ 

value = notif y_next_event_f unc ( frame, event, arg, type); 
/* Determine current state of frame */ 

closed_current = (int) window_get ( frame, FRAME_CLOSED) ; 

/* Change animation if states differ */ 
if (closed_initial != closed current ) { 
if (closed_current ) { 

/* Turn off animation because closed */ 

(void) notify_set_itimer_func(me, my animation, 
ITIMER_REAL , ITIMER_NULL, ITIMERNULL) ; 

} else { 

/* Turn on animation because opened */ 

(void) not if y_set_itimer_f unc (me, my_animation , 
ITIMER_REAL, &NOTIFY_POLLING_ITIMER, 

ITIMER NULL); 



return (value); 
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Discarding the Default Action In the example on the preceding page, you wanted the base event handler to han- 
dle the event (so that the frame gets closed/opened). If the interposed function 
replaces the base event handler, and you don’t want the base event handler to be 
called at all, your interposed procedure should not call 
notif y_next_event_f unc ( ) . For example, your interposed function 
might handle scroll events itself, so you would not want the base event handler to 
perform an additional scroll. 

Interposing on Resize Events Another common use of interposition is to give your application more control 

over the layout of its subwindows. The code is very similar. You call 
notif y interpose event f unc ( ) to interpose your event handler. In 
the event handler, the following fragment could be used: 




Let the default event handler handle the event, then check if the event is a resize 
event. If so, call your own resize ( ) procedure to lay out the subwindows. 



NOTE A WINRESIZE event is not generated until the frame is resized. If you want 
your resize procedure to be called when the window first appears you must do so 
yourself. This is different from a canvas with the CANVAS_RESIZE attribute 
set, whose resize procedure is called the first time the canvas is displayed. 

If the user manually adjusts subwindow sizes using f Control 1 -middle mouse but- 
ton, no WIN_RESIZE event is generated. You can disallow subwindow resizing 
by setting the FRAME_SUBWlNDOWS_ADJUSTABLE attribute to FALSE. 

Example: resize _demo The program resize _demo shows how to achieve more complex window layouts 

than possible using window layout attributes. It is listed in Appendix A, Exam- 
ple Programs. 

Modifying a Frame’s Suppose an application must detect when the user selects the ‘Quit’ menu item in 

Destruction the frame menu, in order to perform some application-specific confirmation. We 

have to interpose in front of the frame’s client destroy event handler using the 
following routine. 

Notif y_error 

not ify_interpose_destroy_f unc (client, destroy_func) 
Notify_client client; 

Notif y_f unc destroy_f unc; 

First, however, you need to understand client destroy events. 
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Destroy Events The Notifier can tell each client to destroy itself. It is possible for a destroy event 

handler to receive two calls concerning client destruction: one call may be a 
status inquiry and the other a demand for termination. Destroy event handlers 
use a status code to determine whether the caller demands actual termination 
(DESTROY_CLEANUP or DESTROY_PROCESS_DEATH), or simply requires an 
indication if it is feasible for the client to terminate at present 
DESTROY_CHECKING). 

Checking If the status argument indicates an inquiry and the client cannot terminate at 

present, the destroy event handler should call not ify_veto_des troy ( ) , 
indicating that termination would not be advisable at this time, and return nor- 
mally. If the status argument indicates an inquiry and the client can terminate 
at present, then the destroy handler should do nothing; a subsequent call will tell 
the client to actually destroy itself. 

This veto option is used, for example, to give a text subwindow the chance to ask 
the user to confirm the saving of any editing changes when quitting a tool. 

Destruction If the status argument is not DES TRO Y_CHECK I NG then the client is being 

told to destroy itself. If status is DES TROY_PROC ES S_DEATH then the 
client can count on the entire process dying and so should do whatever it needs to 
do to cleanup its outside entanglements, e.g., update a file used by other 
processes. Since the entire process is dying, one might choose to not release all 
the resources used within the process, e.g., dynamically allocated memory. 
However, if status is DESTROY_CLEANUP then the client is being asked to 
destroy itself and be very tidy about cleaning up all the process internal resources 
that it is using, as well as its outside entanglements. 

A Typical Destroy Handler A typical destroy handler looks like the following: 
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Example: Interposing a Client Now we can present the example of interposing in front of the frame’s client des- 
Destroy Handler troy event handler. In addition to doing our own confirmation, we prevent dou- 

ble confirmation by suppressing the frame’s default confirmation. 

Note that after having the destroy OK’d by the user, we call 
notify_next_destroy_f unc ( ) before returning. This allows other 
subwindows to request confirmation. 

The code appears on the following page. 
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#include <suntool/sunview . h> 

static Notify_value my_f rame_destroyer ( ) ; 



/* 

* Interpose in front of the frame's destroy event handler 

V 

(void) notif y_interpose_destroy_f unc (frame, 

my_frame_destroyer) ; 

/* Show frame and start dispatching events */ 
window_main_loop( frame) ; 



static Notify_value 

my_f rame_destroyer ( frame, status ) 

Frame frame; 

Destroy_status status; 

if (status == DESTROY_CHECKING ) { 

if {my internal state requires confirmation ) { 

/* 

* Request confirmation from the user 

* (see window_loop() in the index). 

*/ 



i f ( destroy OK’d by user ) { 

/* Tell frame not to do confirmation */ 
window_set( frame, FRAME_NO_CONFIRM, TRUE, 0); 
} else { 

/* 

* Tell the Notifier that the destroy has 

* been vetoed. 

V 

(void) notify_veto_destroy ( frame) ; 

/* 

* Return now so that the destroy event 

* never reaches the frame's destroy handler. 
*/ 

return (NOTIFY_DONE) ; 

} 

} else { 

/* Let frame do normal confirmation */ 
window_set (frame, FRAME_NO_CONFIRM, FALSE, 0); 

1 

] 

/* Let frame get destroy event */ 

return (notif y_next_destroy_f unc (frame, status)); 

1 
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17.6. Porting Programs to Most programs that are ported to SunView are not notification-based. They are 
SunView traditional programs that maintain strict control over the inner control loop. 

Much of the state of such programs is preserved on the stack in the form of local 
variables. The Notifier supports this form of programming so that you can use 
SunView packages without inverting the control structure of your program to be 
notification-based. 

Explicit Dispatching The simplest way to convert a program to coexist with the Notifier is called 

explicit dispatching. This approach replaces the call to 

window_main_loop ( ) , which usually doesn't return until the application ter- 
minates, with the following bit of code: 



r 

# include <suntool/sunview . h> 


\ 


static int my_done; 




extern Notify_error notify_dispatch( ) 


• 


/* Make the frame visible on the screen */ 
window_set ( frame , WIN_SHOW, TRUE, 0); 
while ( !my_done) { 


/* Dispatch events managed by 
(void) notify_dispatch( ) ; 


the Notifier */ 


} 

v 


J 



notif y_dispatch ( ) goes once around the Notifier's internal loop, 
dispatches any pending events, and returns. You should try to have 
notif y_dispatch ( ) called at least once every 1/4 second so that good 
interactive response with SunView windows can be maintained. 

The program bounce (which shows one way to convert an old SunWindows gfx 
subwindow-based program to SunView) uses explicit dispatching. It is 
explained in Appendix C, Converting SunWindows Programs to SunView, and is 
given in full in in Appendix A, Example Programs. 

Implicit Dispatching Explicit dispatching is good when you are performing some computationally 

intensive processing and you want to occasionally give the user a chance to 
interact with your program. There is another method of interacting with the 
Notifier that is useful when you simply want the Notifier to take care of its clients 
and block until there is something of interest to you. This is called implicit 
dispatching. 

This time, we replace the call to window_main_loop ( ) with the following 
bit of code: 
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r 



— 

#include <suntool/sunview . h> 

static int my_done; 

window_set (frame, WIN_SHOW, TRUE, 0); 

/* Enable implicit dispatching */ 

(void) notify_do_dispatch ( ) ; 
while (!my_done) { 
char c; 

/* read allows implicit dispatching by Notifier */ 
if ((n = read ( 0/*stdin*/, &c, 1)) < 0) 
perror ( "my_program" ) ; 



} 

V ) 

notify_do_dispatch( ) allows the Notifier to dispatch events from within 
the calls to read(2) or select(2). The Notifier’s versions of read(2) and 
select(2) won’t return until the normal versions would. They can block 
exactly like the normal versions. 

not if y_no_dispatch ( ) (it takes no arguments) prevents the Notifier from 
dispatching events from within the call to read(2) or select(2). 

When you use either of these dispatching approaches, you will need to find out 
when the frame is ‘Quit’ by the user, in order to know when to terminate your 
program. To do so, interpose in front of the frame’s destroy event handler, as in 
the previous section, so that you can notice when the frame goes away. At this 
point you can call notif y_stop ( ) to break the read(2) or select(2) out 
of a blocking state. 
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17.7. Error Handling 
Error Codes 



Handling Errors 





#include <suntool/sunview . h> 

static int my_done; 

static Notify_value mynot ice_destroy ( ) ; 

/* 

* Interpose in front of the frame's destroy event handler 

V 

(void) notif yinterposedestroyf unc (frame, 

mynot ice_destroy ) ; 

static Notify_value 
my_notice_destroy ( frame, status) 

Frame frame; 

Destroy_status status; 

if (status ! = DESTROY_CHECKING) { 

/* Set my flag so that I terminate my loop soon */ 
my__done = 1; 

/* Stop the notifier if blocked on read or select */ 
(void) notif y_stop () ; 

} 

/* Let frame get destroy event */ 

return (notif y_next_destroy_func (frame, status)); 

v J 



Every call to a notifier routine returns a value that indicates success or failure. 
Routines that return an enumerated type called Notif y_error deliver 
NOTIF Y_OK (zero) to indicate a successful operation, while any other value 
indicates failure. Routines that return function pointers deliver a non-null value 
to indicate success, while a value of NOTIFY_FUNC_NULL indicates an error 
condition. 

When an error occurs, the global variable notif y_errno describes the failure. 
The Notifier sets notif y err no much like UNIX system calls set the global 
errno; that is, the Notifier only sets notify errno when it detects an error 
and does not reset it to NOTIFY OK on a successful operation. A table in the 
SunView System Programmer’s Guide lists each possible value of 
notify errno and its meaning. 

Most of the errors returned from the Notifier indicate a programmer error, e.g., 
the arguments are not valid. Often the best approach for the client is to print a 
message if the return value is non-zero and exit. The procedure 
notif y_perror ( ) takes a string which is printed to stderr, followed by a 
colon, followed by a terse description of notif y_errno. This is done in a 
manner analogous to the UNIX perror(3) call. 
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Debugging 

NOTIFY_ERROR_ 

Stop in not if y_ 
or fprintf(3S) 

notify_dump 



Here are some debugging hints that may prove useful when programming: 

ABORT Setting the environment variable NOTlFY_ERROR_ABORT to YES will cause 

the Notifier to abort with a core dump when the Notifier detects an error. This is 
useful if there is some race condition that produces notifier error messages that 
you are having a hard time tracking down. 

perror ( ) If you are getting notifier error messages, but don’t know from where, try putting 

a break point on the entry to either notif y perror ( ) or f printf (3S). 
Trace the stack to see what provoked the message. 

The following call can be made from the debugger or your program to dump a 
printout of the state of the Notifier: 

void 

notify_dump( client, type, file) 

Notify_client client; 
int type; 

FILE *f ile; 

The state of client is dumped to f ile based on the value of type. If 
client is 0 then all clients are dumped. If type is 1 then all the registered 
event handlers are dumped. If type is 2 then all the events pending for delivery 
are dumped. If type is 3 then both the registered event handlers and the events 
pending for delivery are dumped. If file is 1 then stdout is assumed. If file 
is 2 then stderr is assumed. To be able to call notify_dump ( ) you need to 
reference it from some place in your program so that it gets loaded into your 
binary. 
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1 

Attribute Utilities 



This chapter describes macros and functions that are provided as utilities to be 
used with attributes. 



18.1. Character Unit By default in SunView, coordinate specification attributes interpret their values 

Macros in pixel units. For applications that don’t make heavy use of images, it is usually 

more convenient to specify positions in character units — columns and rows 
rather than xs and ys. To this end two macros ATTR ROW ( ) and ATTR COL ( ) 
are provided, which interpret their arguments as rows or columns, respectively, 
and convert the value to the corresponding number of pixels, based on the 
subwindow’s font, as specified by WIN_FONT. ATTR_ROW ( ) and 
ATTR_COL ( ) take as arguments any expression yielding an integer. The use of 
these macros as an operand in an expression is restricted to adding a pixel offset 
(e.g., ATT R_RO W (5 ) + 2). Examples of legal and illegal usage are given in the 
table below. 



Table 18-1 



Example uses of the ATTR_ROW ( ) and ATTR_COL ( ) macros 



Attribute/ Value 



PANEL_ITEM_X, 5 
PANEL_ITEM_Y, 10 
PANEL_I TEM_X , ATTR_COL(5) 

PANEL_ITEM_X, ATTR_COL(~5) 

PANEL_ITEM_X , ATTR_COL ( 5+2 ) 
PANEL_ITEM_X, ATTR_COL ( 5 ) +2 
PANEL_ITEM_X, ATTR_COL ( 5 ) - 1 
PANEL_ITEM_Y, ATTR_ROW(10) 
PANEL_ITEM_Y, ATTR_ROW( -10 ) 
PANEL_ITEM_Y, ATTR ROW( 10+2 ) 

PANEL_I TEM_Y , ATTR_ROW( 10 ) +2 
PANEL_I TEM_Y , ATTR_ROW( 10 ) - 1 
PANELITEMX, ATTR_COL( 10 ) + ATTR_COL ( 2 ) 
PANEL ITEM X, 2*ATTR COL('IO) 



Interpretation 

5 pixels from left 
10 pixels from top 
column 5 
column -5 
column 7 

2 pixels to right of col 5 

1 pixel to left of col 5 
row 10 

row -10 
row 12 

2 pixels down from row 10 
1 pixel up from row 10 
illegal 

illegal 



NOTE ATTR_ROW ( ) and ATTR_COL ( ) treat their arguments as character positions 
rather than lengths. In other words, when you use ATTR_ROW(5), the pixel 
value that is computed includes the top margin. Similarly, the pixel value com- 
puted using attr_COL(5) includes the left margin. 
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These macros can be used with the panel attributes or the window attributes such 
as WIN_X, WIN_HEIGHT, etc. 

Both the attributes and the ATTR_ROW ( ) and ATTR_COL ( ) macros are zero- 
based — that is, the first row is row zero. 

If you want to use lengths rather than positions, you can use the alternate macros 
ATTR_ROWS ( ) and ATTR_COLS ( ) . Examples of the differences between the 
character position and length macros are given in the table below. 

Table 18-2 Example uses of the ATTR_ROWS ( ) and ATTR_COLS ( ) macros 



Attribute/Value 


Interpretation 


WIN_WIDTH, ATTR_COL( 80 ) 


80 characters wide + left margin 


WIN_WIDTH, ATTR_COLS (80) 


exactly 80 characters wide 


WIN_HEIGHT , ATTR_ROW (24) 


24 lines high + top margin 


WIN_HEIGHT , ATTR_ROWS (24) 


exactly 24 lines high 


PANEL_ITEM_X, ATTR_COL(5) 


col 5 (left margin + 5 character widths) 


PANEL_ITEM_X , ATTR_COLS(5) 


5 character widths from the left edge 


PANEL_ITEM_Y, ATTR_ROW(5) 


row 5 (top margin + 5 row heights) 


PANEL_ITEM_Y, ATTR_ROWS(5) 


5 row heights from the top edge 



18.2. Creating Reusable You may want to create an attribute list that can be passed to different routines. 

Attribute Lists You can do this either by creating the list explicitly, or by using the routine 

attr_create_list ( ). 



To create an attribute list explicitly, define a static array of char *, which is 
initialized (or later filled in with) the desired attribute/value pairs. Note that 
non-string values must be coerced to type char *: 



r 


static char *attributes [ ] = { 


'v 




( char* ) PANEL_LAB EL_S TR ING , 


"Name: ", 




( char* ) PANEL_VALUE , 


"Goofy ", 




( char* ) PANEL_NOTIFY_PROC , 
0 } 


( char * ) name_item_proc , 









To make an attribute list dynamically, use: 

Attr_avlist 

a ttr_create_list( attributes ) 

<attribuie-list> attributes ; 

attr create l is t ( ) allocates storage for the list it returns. It is up to you 
to free this storage when no longer needed, as in: 
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The free ( ) procedure is the standard UNIX f ree(3) routine. 



Default Attributes The code below shows how to use attr create list ( ) in conjunction 

with the attribute ATTR_LIST to support default attributes in a panel. 



— 

int 


text proc(), name proc(); 


\ 


Panel_i tem 


name item, address_item; 




Pixfont * 


big font, *small font; 




Attr avlist 


defaults ; 




defaults = 


attr create list( 






PANEL_SHOW_I TEM , 


FALSE, 




PANEL_LABEL_FONT , 


big_font , 




PANEL_VALUE_FONT , 


small font, 




PANEL_NOTIFY_PROC , 
0 ) ; 


text proc. 


name item = 


panel create item( PANEL TEXT, 






ATTR_LIST , 


defaults , 




PANEL NOTIFY PROC, 
0 ) ; 


name proc, 


address item 


= panel create item(PANEL TEXT, 






ATTR_LIST , 


defaults , 




PANEL SHOW ITEM, 


TRUE, 




PANEL VALUE FONT, 
0); 


big font, 

/ 



The special attribute ATTR_LIST takes as its value an attribute list. In the 
above example, first an attribute list called defaults is created. Then, by 
mentioning defaults first in the attribute lists for subsequent item creation 
calls, each item takes on those default attributes. Subsequent references to an 
attribute override the setting in defaults since the last value mentioned for an 
attribute is the one which takes effect. 

18.3. Maximum Attribute The maximum length of attribute-value lists supported by the SunView packages 
List Size (see ATTR_STANDARD_SIZE in <sunwindow/attr . h>) is 250. If the 

number of attributes in a list you pass to SunView exceeds this size, the attribute 
package prints 




on standard output and exits with exit status 1. 
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19 



Sun View Interface Summary 



This chapter contains tables summarizing the data types, functions and attributes 
which comprise the SunView programmatic interface . 100 

The tables correspond to the chapters in this book, but are in alphabetical order: 
Alerts, Canvases, Cursors, Data Types, Icons, Input (including events and input- 
related window atttributes). Menus, the Notifier, Panels, Pixwins, Scrollbars, 
Text Subwindows, TTY Subwindows and Windows (including frames and frame 
command line arguments). 

Note that the order of the chapters is different than the order of the tables. The 
chapter on windows (including frames) comes first, followed by canvases, input, 
pixwins, text subwindows, panels, alerts, tty subwindows, menus, cursors, icons, 
scrollbars, the Selection Service, and the Notifier. 

Within each topic, the attribute tables come first, then the functions and macros, 
then miscellaneous tables. 

To help distinguish where one table ends and another begins, the start of each 
table is marked with a horizontal grey bar. 



100 This chapter does not include a table for the Selection Service functions; see the SunView System 
Programmer’ s Guide for a complete discussion of the Selection Service interface. 
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Table 19-1 Alert Attributes 



Attribute 


Type 


Description 


ALERT_BUTTON 


char *, int 


A string to be displayed in a button and a value to associate with it. The 
value specified with the string will be returned when the button is 
selected. The value may be any integer, but should not be a value 
predefined by the alerts package; that is, not ALERT YES, ALERT NO, 
ALERT_FAILED, or ALERT^DEF AULT TRIGGERED). 

See the values given in the Alert Functions table. 


ALERT_BUTTON_FONT 


Pixfont * 


Font used for buttons. Default is the font specified for menus, which is 
MenulFont in defaultsedit or screen . b . 14 if no default is specified. 


ALERT_BUTTON_NO 


char * 


A string that is associated with the accelerated 
NO (cancel, don’t do it) button which is triggered via a 
keyboard accelerator. The value returned if this button is selected 
(or the accelerator is triggered) will be ALERT_NO. Only one instance 
of this attribute is allowed. 


ALERT_BUTTON_YES 


char * 


A string to associate with the accelerated 

YES (ie. confirm, continue, do it) button which is also triggered via a 
keyboard accelerator. The value returned when this button is selected 
(or the accelerator is triggered) will be ALERT YES. Only one instance 
of this attribute is allowed. 


ALERT_MESSAGE_FONT 


Pixfont * 


Font used for message strings. 

The default is the same as Client Frame (if specified) otherwise it is the 
same as SunView/Font. 


ALERT MESSAGE STRINGS 


list char* 


Strings to be displayed in the message 

area of the alert panel. The default is to be determined. 


ALERT_MESSAGE_STRINGS_ARRAY_PTR 


array char* 


Same as ALERT_MESSAGE_STRINGS 

except the client need not know the actual strings being passed, just 
that the value is pointer to first of null terminated array of strings. 
The alerts package will cast the value into a type char * *. 


ALERT_NO BEEPING 


int 


Allows the client to specify that no beeping should 

take place reguardless of defaults database setting. The default for this 

option is FALSE; that is, beep however many times database specifies. 
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Table 19-1 


Alert Attributes — Continued 




Attribute 


Type 


Description 


ALERT_ 


OPTIONAL 


boolean 


Specifies whether an optional alert will be enabled 
or disabled. You make an alert a 
courtesy alert by specifing the ALERT OPTIONAL 
attribute in the attribute list passed to 

alert prompt ( ). 


ALERT_ 


POSITION 


int 


Specifies the position of the alert. 

Default is ALERT_CLIENT_CENTERED unless client_frame = NULL 
NULL causes the alert to default to ALERT_SCREEN_CENTERED 
regardless of this setting. 








Possible values that may be passed are: ALERT_SCREEN_CENTERED, 
ALERT_CLIENT_CENTERED , and ALERT_CLIENT_OFFSET. 

Use WIN_X and WIN_Y for the offset attributes. This position describes 
where the “center” of an alert should be. 


ALERT 


TRIGGER 


int 


This special attribute allows the client to 

specify a SunView event which should cause the alert to return. The 
default is not to return unless an actual button has been selected 
or the other YES/NO accelerators are seen. When this event is triggered, 
the value returned will be ALERT TRIGGERED. 
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Table 19-3 Canvas Attributes 






g 


Attribute 


Type 


Description 


CANVASAUTOCLEAR 


boolean 


If TRUE, repaint area of canvas pixwin is cleared before, 
repaint proc is called. Default: TRUE unless the canvas is retained. 


CANVAS^AUTO EXPAND 


boolean 


If TRUE, canvas width and height are never allowed to be 
less than the edges of the canvas pixwin. Default: TRUE. 


CANYASAUTO SHRINK 


boolean 


If TRUE, canvas width and height are never allowed to be 
greater than the edges of the canvas pixwin. Default: TRUE. 


CANVAS_FAST_MONO 


boolean 


If TRUE, tells canvases and graphics subwindows to use 

the monochrome overlay plane of the Sun-3/1 10 display. Default: FALSE. 


CANVAS_FIXED_IMAGE 


boolean 


If TRUE, canvas package assumes that client is drawing a fixed-size image 
whose rendering does not depend on the size of the canvas. Default: TRUE. 


CANVAS_HEIGHT 


int 


Height of object being drawn. Default: height of usable window, which is 

WIN_HEIGHT - (SCROLL_THICKNESS of WIN_HORIZONTAL_SCROLLBAR) - 
CANVAS_MARGIN*2. 


CANVAS_MARGI N 


int 


Margin to leave around the canvas pixwin from inside of window. Default: 0. 


CANVAS_PIXWIN 


Pixwin * 


Pixwin for drawing. Get only. 


CANVAS_REPAINT_PROC 


(procedure) 


Called when repaint needed, even if retained. Default: NULL. Form: 
repaint proc(canvas, pixwin, repaint area) 
Canvas canvas; 

Pixwin *pixwin; 

Rectlist *repaint area; 


CANVAS__RESIZE_PROC 


(procedure) 


Called when canvas width or height changes. Default: NULL. Form: 
resize_proc (canvas , width, height) 

Canvas canvas; 
int width; 
int height; 


CANVAS_RETAINED 


boolean 


If TRUE, image is backed up for repaint. Default: TRUE. 


CANVAS_WIDTH 


int 


Width of object being drawn. Default: width of usable window, which is 

WIN_WIDTH - (SCROLL_THICKNESS of WIN_VERTICAL_SCROLLBAR) - 
CANVAS_MARGIN*2. 
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Table 19-4 Canvas Functions and Macros 



Definition 


Description 


Event * 

canvas event (canvas, event) 
Canvas canvas; 

Event *event; 


Translates the coordinates of event from the space of the 

canvas subwindow to the space of the logical 

canvas (which may be larger and scrollable). That is, 

the client passes in a pointer to an event, then the 

function does an event set x( event, translated x) 

and an event set_y (event, translated y). 

It then returns the same pointer that was 
passed in. 


Pixwin * 

canvas pixwin ( canvas ) 
Canvas canvas; 


Returns the pixwin to use when drawing into 
the canvas with the pw* ( ) routines. 


Event * 

canvas window_event ( canvas , event) 
Canvas canvas; 

Event *event; 


Translates the coordinates of event to the space of the 
canvas subwindow from the space of the logical 
canvas. 
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Table 19-5 Cursor Attributes 





Attribute 


Value Type 


Description 



Crosshairs stick to borders. Default: FALSE. 



CURSOR CROSSHA I RBORDERGRAVITY boolean 

CURSORCROSSHAIRCOLOR int 

CURSOR_CROSSHAIR_GAP int 

CURSOR_CROSSHAIR_LENGTH int 

CURSOR_CROSSHAIR_OP int 

CURSOR_CROSSHAIR_THICKNESS int 

CURSOR_FULLSCREEN boolean 

CURSOR_HOR I Z_HA I R_BORDER_GR AV I T Y boolean 

CURSORHORI Z_HAIR_COLOR int 

CURSOR_HORIZ_HAIR_GAP int 

CURSOR_HORI Z_HAIR LENGTH int 

CURSOR_HORIZ_HAIR_OP int 

CURSOR _HORIZ_HAIR_THICKNESS int 

CURSOR__IMAGE Pixrect * 

CURSOR OP int 

CURSOR SHOW_CROSSHA IRS boolean 

CURSOR_SHOW_CU RSOR boolean 

CURSOR SHOW_HORI Z_HA I R boolean 

CURSOR SHOW VERT HAIR boolean 



A 



Color for crosshairs. Default: 1. (Note: the color displayed 
depends on the settings in your colormap segment). 

Half-length of space to leave untouched from intersection of 
crosshairs. Value of CURSOR_TO_EDGE extends crosshairs to 
edge of cursor rect. Default: 0. 

Half-length of crosshairs. Default: CURSOR_TO_EDGE. 

Raster op for drawing crosshairs. Default: PIX SRC. 

Thickness of crosshairs. Maximum value is 
CURSOR_MAX_HAIR_THICKNESS (5). Default: 1. 

Clip crosshairs to edge of screen not window. Default: FALSE. 

Horizontal crosshair sticks to borders. Default: FALSE. 

See CURSOR_HORI Z_HAIR_COLOR 

See CURSOR_CROSSHAIR_GAP. 

See CURSOR_CROSSHAIR_LENGTH. 

Raster op for drawing horizontal crosshair. Default: P IX SRC. 

See CURSOR CROSSHAIR_THICKNESS. 

Cursor’s image. Default: 16 x 16 x 1 blank pixrect. 

Raster op for drawing cursor image. 

Default: PIX SRC | PIX DST. 

Show or don’t show crosshairs. Default: FALSE. 

Show or don’t show cursor image. Default: TRUE. 

Show or don’t show horizontal crosshair. Default: FALSE. 

Show or don’t show vertical crosshair. Default: FALSE. 



wsun 

Xr microsystems 



Revision A, of March 27, 1 990 








292 Sun View Programmer’s Guide 



Table 1 9-5 Cursor Attributes — Con timed. 



Attribute 

CURSOR_VERT_HAIR _BORDER_GRAVI TY 

CURSOR_VERT_HAIR_COLOR 

CURSOR VERT_HA I R_GAP 

CURSOR_VERT_HAIR_LENGTH 

CURSOR_VERT_HAIR_OP 

CURSOR_VERT_HAIR_THICKNESS 

CURSOR_XHOT 

CURSOR YHOT 



Value Type 


Description 


boolean 


Vertical crosshair sticks to borders. Default: FALSE. 


int 


See CURSOR_CROSSHAIR_COLOR 


int 


See CURSOR CROSSHAIR GAP. 


int 


See CURSOR_CROSSHAIR_LENGTH. 


int 


Raster op for drawing vertical crosshair. Default: PIX SRC. 


int 


See CURSOR_CROSSHAIR_THICKNESS. 


int 


Hot spot x coordinate. Default: 0. 


int 


Hot spot y coordinate. Default: 0. 
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Table 19-6 Cursor Functions 



Definition 


Description 


Cursor 

cursor copy(src cursor) 
Cursor src_cursor; 


Creates and returns a copy of src cursor. 


Cursor 

cursor create(attributes) 
<attribute-list> attributes; 


Creates and returns the opaque handle to a cursor. 


void 

cursor destroy ( cursor ) 
Cursor cursor; 


Destroys cursor. 


caddr t 

cursor get(cursor, attribute) 
Cursor cursor; 

Cursor attribute attribute; 


Retrieves the value for an attribute of cursor. 


void 

cursor set(cursor, attributes) 
Cursor cursor; 

<attribute-list> attributes; 


Sets the value for one or more attributes of cursor, 
attributes is a null-terminated attribute list. 
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Table 19-7 Data Types 



Data Type 


Description 


Canvas 


Pointer to an opaque structure which describes a canvas. 


Cursor 


Pointer to an opaque structure which describes a cursor. 


Destroy_status 


Enumeration: DESTROY_PROCESS_DEATH, 
DESTROY_CHECKING, or DESTROY_CLEANUP. 


Event 


The structure which describes an input event: 
typedef struct inputevent { 
short ie_code; 
short ie_flags; 
short ie shiftmask; 
short ie locx; 
short ie locy; 
struct timeval ie time; 

} Event; 


Frame 


Pointer to an opaque structure which describes a frame. 


Icon 


Pointer to an opaque structure which describes a icon. 


Inputmask 


Mask specifying which input events a window will receive. 


Menu 


Pointer to an opaque structure which describes a menu. 


Menu_attribute 


One of the menu attributes (MENU *). 


Menu generate 


Enumerated type of the operation parameter passed to generate procs: 

MENU_CREATE, MENU_DESTROY, MENU_NOTIFY_CREATE or MENUJNOTIFY DESTROY. 


Menu_item 


Pointer to an opaque structure which describes a menu item. 


Notify_arg 


Opaque client optional argument. 


Notify_destroy 


Enumeration: NOTIFY_SAFE, NOTIFY_IMMEDI ATE. 
(See also Notify event type). 


Not if y_event 


Opaque client event. 
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Table 19-7 


Data Types — Continued 


Data Type 


Description 


Notif y_error 


Enumeration of errors for notifier functions: 

NOT IFY_OK, NOTIFY_UNKNOWN_CLIENT, NOTIFY_NO_CONDI TION, 

NOT IFY_BAD_ITIMER, NOT I FY_B AD_S IGNAL, NOTIFY_NOT_STARTED, 
NOT IFY_DESTROY_VETOED, N0TIFY_I NTERNALERROR, NOTIFY_SRCH, 
NOT I FY BADF, NOT I FY_NOMEM, NOT I FY_I NVAL, or NOT I FY_FUNC_LIMIT. 


Notify_event_type 


Enumeration: NOTIFY_SAFE, NOTIFY_IMMEDI ATE. 


Notif y_func 


Notifier function. 


Notify signal_mode 


Enumeration: NOTI FY_SYNC, NOTIFY_ASYNC. 


Notif y_value 


Enumeration of possible return values for client notify procs: 

NOT I FY_DONE, NOT I FY_ IGNORED, or NOTIFYUNEXPECTED. 


Panel 


Pointer to an opaque structure which describes a panel. 


Panel_attribute 


One of the panel attributes (PANEL *). 


Panel_item 


Pointer to an opaque structure which describes a panel item. 


Panel_setting 


Enumerated type returned by panel text notify ( ); 
also type of repaint argument to panel pa int ( ). 
See the Panels chapter and <suntool/panel . h>. 


Pixfont 


The structure representing a font (for definition see the Pixrect Reference Manual). 


Pixrect 


The basic object of pixel manipulation in the SunView window system. Pixrects 
include both a rectangular array of pixels and the means of accessing operations 
for manipulating those pixels (for definition see the Pixrect Reference Manual). 


Pixwin 


The basic imaging element of the SunView window system. While, for 
historical reasons, its fields are public, clients should treat it as an opaque handle. 


Rect 


The structure describing a rectangle: 

typedef struct rect { 
short r left; 
short r top; 
short r width; 
short r height; 

} Rect; 
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Table 19-7 


Data Types — Continued 


Data Type 


Description 


Rectlist 


A list of rectangles: 

typedef struct rectlist [ 
short rl_x, rl_y; 
Rectnode *rl_head; 
Rectnode *rl__tail; 

Rect rl_bound; 

} Rectlist; 




typedef struct rectnode { 
Rectnode *rn_next; 

Rect rn_rect; 

} Rectnode; 


Scroll_motion 


Enumerated type representing possible scrolling motions: 
SCROLL_ABSOLUTE, SCROLL_FORWARD, SCR0LL_MAX_T0_P0INT, 
SCROLL_PAGE_FORWARD, SCROLL_LINE_FORWARD, 
SCROLL_BACKWARD, SCROLL_POINT_TO_MAX, 
SCROLL_PAGE_BACKWARD, or SCROLL_LINE_BACKWARD. 


Scrollbar 


The opaque handle for a scrollbar. 


Scrollbar attribute 


One of the scrollbar attributes (SCROLL_*). 


Scrollbar_setting 


The value of an enumerated type scrollbar attribute. 


Textsw 


Pointer to an opaque structure which describes a text subwindow. 


Textsw index 


An index for a character within a text subwindow. 


Textsw enum 


Enumerated type for various text subwindow attribute values: 
TEXTSW_ALWAYS, TEXTSW_NEVER, TEXTSW_ONLY, 
TEXTSW I F_AUTO_SCROLL, TEXTSW_CLIP, 
TEXTSW_WRAP_AT_CHAR, TEXTSW_WRAP_AT_WORD. 


Textsw_status 


Enumeration describing the status of text subwindow operations: 

TEXTSW_STATUS__OKAY, TEXTSW_STATUS_BAD_ATTR, 

TEXTSW_STATUS_BAD_ATTR_VALUE, TEXTSW_STATUS_CANNOT_ALLOCATE, 
TEXTSW_STATUS_CANNOT_OPEN_INPUT, or TEXTSW_STATUS_OTHER_ERROR, 


Tty 


Pointer to an opaque structure which describes a tty subwindow. 


Window 


Pointer to an opaque structure which describes a window. 
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Table 19-7 


Data Types — Continued 


Data Type 


Description 


Win alarm 


Programmable alarm structure 
typedef struct alarmval { 
int beep_num; 
int flashjnum; 
struct timeval beep_duration; 
> Win_alarm; 


Window_attribute 


One of the window attributes (WIN *). 


Window_type 


Type of window, retrieved via the WIN TYPE attribute. One of: 

FRAME_TYPE, PANEL_TYPE, CANVAS_TYPE, TEXTSW_TYPE, or TTY_TYPE. 
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Table 19-8 Help A ttribu tes 





The attribute and functions listed here are discussed in the SunView 1.80 Update , 
part number 800-4738-10. 






Attribute 


Type Description 


HELP_DATA 102 


char 4, define tlie request Atring far retrieving Spot Help, request Airing faunal: 

package-.key 

wiieie package . i n f o ia the help text file 
key ii the key Atiing unking the lielp text 



Table 19-9 Help Functions and Macros 



Definition 


Description 


void 




help rpc register (help_func) 
void ( *help func) ( request_string) 

char *request_string ; 


register the More Help function 


help rpc unregister (help func) 


deregister the More Help function 


help set more_f unc ( help_on_help_f unc ) 


supply a function to provide Spot Help 


void (* help on help func)(); 


on the More Help function itself 
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Table 19-10 Icon Attributes 









Attribute 


Type 


Description 


ICON_FONT 


Pixfont * 


Font for icon’s label. 


ICON_HEIGHT 


int 


Icon’s height in pixels. Default: 64. 


ICON_IMAGE 


Pixrect * 


Memory pixrect for icon’s image. 


ICON__IMAGE RECT 


Rect * 


Rect for icon’s image. Default: origin (0, 0), width 64, height 64. 


ICON_LABEL 


char * 


Icon’s label. 


ICON_LABEL_RECT 


Rect * 


Rect for icon’s label. Default: origin (0, 0), width 0, height 0. 


ICON_WIDTH 


int 


Icon’s width in pixels. Default: 64. 
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Table 19-12 Event Codes 



Event Code 


Description 


Value (for debugging) 


ASCI I_FIRST 


Marks beginning of ASCII range 


0 


ASCII_LAST 


Marks end of ASCII range 


127 


META_FIRST 


Marks beginning of META range 


128 


META_LAST 


Marks end of META range 


255 


ACTION_ERASE_CHAR_BACKWARD 


Erase char to the left of caret 


31745 


AC T I ON_ERASE_CHAR_FORWARD 


Erase char to the right of caret 


31746 


ACT I ON_ERAS E_WORD_BACKWARD 


Erase word to the left of caret 


31747 


ACTION_ERASE_WORD_FORWARD 


Erase word to the right of caret 


31748 


ACTION_ERASE_LINE_BACKWARD 


Erase to the beginning of the line 


31749 


ACTION ERAS E_L I NE_END 


Erase to the end of the line 


31750 


ACTION_GO_CHAR_BACKWARD 


Move the caret one character to the left 


31752 


ACT I ON_GO_CHAR_FORWARD 


Move the caret one character to the right 


31753 


AC T I ON_GO WO RD_B ACKW ARD 


Move the caret one word to the left 


31754 


AC T I ON_GO_WO RD_END 


Move the caret to the end of the word 


31756 


AC T I ON_GO_WO RD_FO R WA RD 


Move the caret one word to the right 


31755 


ACTION_GO_LINE_BACKWARD 


Move the caret to the start of the line 


31757 


AC T I ON_GO_L I NE_END 


Move the caret to the end of the line 


31759 


ACT I ON_GO_LI NE_FORWARD 


Move the caret to the start of the next line 


31758 


ACTION_GO_COLUMN_BACKWARD 


Move the caret up one line, 
maintaining column position 


31761 


ACTION_GO_COLUMN_FORWARD 


Move the caret down one line, 
maintaining column position 


31762 


ACTION_GOJDOCUMENT_START 


Move the caret to the beginning of the text 


31763 


ACTION_GO_DOCUMENT_END 


Move the caret to the end of the text 


31764 


ACTION_STOP 


Stop the operation 


31767 


ACTIONAGAIN 


Repeat previous operation 


31768 


ACTION PROPS 


Show property sheet window 


31769 


ACT ION_UNDO 


Undo previous operation 


31770 


ACTION FRONT 


Bring window to the front of the desktop 


31772 


ACTIONBACK 


Put the window at the back of the desktop 


31773 


ACT IONOPEN 


Open a window from its icon form or close 
if already open) 


31775 


ACTION_CLOSE 


Close a window to an icon 


31776 


ACTION_COPY 


Copy the selection to the clipboard 


31774 


ACTION_PASTE 


Copy clipboard contents to the insertion point 


31777 


ACTION_CUT 


Delete the selection, put on clipboard 


31781 


ACTION_COPY THEN__PASTE 


Copies then pastes text 


31784 


ACTION_FIND FORWARD 


Find the text selection to the right of the caret 


31779 


AC T I ON_FI ND_B ACKWARD 


Find the text selection to the left of the caret 


31778 


ACTION_FIND_AND_REPLACE 


Show find and replace window 


31780 


ACTION_SELECT_FIELD_FORWARD 


Select the next delimited field 


31783 
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Table 19-12 Event Codes — Continued 



Event Code 


Description 


Value (for debugging) 


ACTION_SELECT_FIELD_BACKWARD 


Select the previous delimited field 


31782 


ACTION_MATCH_DELIMITER 


Selects text up to a matching delimiter 


31894 


ACTIONQUOTE 


Causes next event in the input stream to 
pass untranslated by the keymapping system 


31898 


ACTION_EMPTY 


Causes the subwindow to be emptied 


31899 


ACT ION_STORE 


Stores the specified selection as a new file 


31785 


ACTION_LOAD 


Loads the specified selection as a new file 


31786 


AC T I ON_GET_F I LEN AME 


Gets the selected filename 


31788 


AC T I ON_SET_DI RECTORY 


Sets the directory to the selection 


31788 


ACTION_INCLUDE_FILE 


Selects the current line (in pending-delete mode) 
and attempts to insert the file described by that selection 


31891 


ACTION_CAPS_LOCK 


Toggle caps lock state 


31895 


PANEL_EVENT_CANCEL 


The panel or panel item is no longer “current” 


32000 


PANEL EVENT MOVE_ IN 


The panel or panel item was entered 
with no mouse buttons down 


32001 


PANEL_EVENT_DRAG_IN 


The panel or panel item was entered with one or more 
mouse buttons down 


32002 


SCROLL_REQUEST 


Scrolling has been requested 


32256 


SCROLL_ENTER 


Locator (mouse) has moved into the scrollbar 


32257 


SCROLL^EXIT 


Locator (mouse) has moved out of the scrollbar 


32258 


LOC_MOVE 


Locator (mouse) has moved 


32512 


LOC_STILL 


Locator (mouse) has been still for 1/5 second 


32513 


LOC_WINENTER 


Locator (mouse) has entered window 


32514 


LOC_WINEXIT 


Locator (mouse) has exited window 


32515 


LOCDRAG 


Locator (mouse) has moved while a button was down 


32516 


LOCRGNENTER 


Locator (mouse) has entered a region of the window 


32519 


LOC_RGNEXIT 


Locator (mouse) has exited a region of the window 


32520 


LOC_TRAJECTORY 


Inhibits the collapse of mouse motions; clients receive 
LOC TRAJECTORY events for every locator motion 
the window system detects. 


32523 


WIN_REPAINT 


Some portion of window requires repainting 


32517 


WIN RESIZE 


Window has been resized 


32518 


WIN_STOP 


User has pressed the stop key 


32522 


KBD_REQUEST 


Window is about to become the focus of keyboard input 


32526 


KBD_USE 


Window is now the focus of keyboard input 


32524 


KBD_DONE 


Window is no longer the focus of keyboard input 


32525 


SHIFT_LEFT 


Left shift key changed state 


32530 


SHIFT_RIGHT 


Right shift key changed state 


32531 


SHIFT_CTRL 


Control key changed state 


32532 


SHIFT_META 


Meta key changed state 


32534 


SHIFT_LOCK 


Shift lock key changed state 


32529 
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Table 19-12 


Event Codes — Continued 




Event Code 


Description 


Value (for debugging) 


SHIFT_CAPSLOCK 


Caps lock key changed state 


32528 


BUT ( i ) 


Locator (mouse) buttons 1-10 


BUT(l) is 32544 


MS_LEFT 


Left mouse button 


32544 


MS_MIDDLE 


Middle mouse button 


32545 


MS_RIGHT 


Right mouse button 


32546 


KEY_LEFT ( i ) 


Left function keys 1-15 


KEY__LEFT ( 1 ) is 32554 


KEY_RIGHT(i) 


Right function keys 1-15 


KEY_RIGHT ( 1 ) is 32570 


KEY_TOP ( i ) 


Top function keys 1-15 


KEY_TOP ( 1 ) is 32586 
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Table 19-13 Event Descriptors 



Event Descriptor 


Explanation 


WIN_NO_EVENTS 


Clears input mask — no events will be accepted. Note: the 
effect is the same whether used with a consume or an 
ignore attribute. A new window has a cleared input mask. 


WIN_ASCI I_EVENTS 


All ASCH events. ASCII events that occur while the META 
key is depressed are reported with codes in the META range. 
In addition, cursor control keys and function keys are 
reported as ANSI escape sequences: a sequence of events 
whose codes are ASCII characters, beginning with <ESC>. 


WIN_IN_TRANSIT_EVENTS 


Enables immediate LOC_MOVE, LOC_WINENTER, and 
LOC WINEXIT events. Pick mask only. Off by default. 


WIN_LEFT__KEYS 


The left function keys, KEYJLEFT(l) — KEY_LEFT(15). 


WIN_MOUSE_BUTTONS 


Shorthand for MS_RIGHT, MS_MIDDLE and MS_LEFT. 
Also sets or resets WIN_UP_EVENTS. 


WIN_RIGHT_KEYS 


The right function keys, KEY_RIGHT(1) — KEY_RIGHT(15). 


WIN_TOP_KEYS 


The top function keys, KEY_TOP(l) — KEY_TOP(15). 


WIN_UP_ASC I IEVENTS 


Causes the matching up transitions to normal 
ASCII events to be reported — if you see an ’a’ 
go down, you’ll eventually see the matching ’a’ up. 


WIN UP_EVENTS 


Causes up transitions to be reported for button 
and function key events being consumed. 
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Table 19-14 


Input-Related Window Attributes 




Attribute 


Value Type 


Description 


WIN INPUT_DESIGNEE 


int 


Window which gets events this window doesn’t consume. 






(Note that the value must be the designee’s WIN DEVICE NUMBER). 


WI N_GRAB_ALL_I NPUT 


boolean 


Window will get all events regardless of location. 


WIN_KBD_FOCUS 


boolean 


Whether or not the window has the keyboard focus. 


WIN KBD_INPUT_MASK 


Inputmask * 


Window’s keyboard inputmask. 


WIN_PICK_INPUT_MASK 


Inputmask * 


Window’s pick inputmask. 


WIN_CONSUME_KBD_EVENT 


short 


Window will receive this event. 


WIN_IGNORE_KBD_EVENT 


short 


Window will not receive this event. 


WIN_CONSUME_KBD_EVENTS 


short list 


Null terminated list of events window will receive. 


WIN_IGNORE_KBD_EVENTS 


short list 


Null terminated list of events window will not receive. 


WIN_CONSUME_PICK_EVENT 


short 


Window will receive this pick event. 


WIN_IGNORE_PICK_EVENT 


short 


Window will not receive this pick event. 


WIN_CONSUME_PICK_EVENTS 


short list 


Null terminated list of pick events window will receive. 


WIN _IGNORE_PICK_EVENTS 


short list 


Null terminated list of pick events window will not receive. 
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Table 19-15 


Menu Attributes 










Attribute 


Value Type 


Description 


MENU_ACTION_IMAGE 


Pixrect *, action proc 


Create image menu item with action proc. Set only. 


MENUACT I ONI TEM 


char *, action proc 


Create string menu item with action proc. Set only. 


MENU_APPEND__ITEM 


Menu_item 


Append item to end of menu. Set only. 


MENU_BOXED 


boolean 


If TRUE, a single-pixel box will be drawn around 
every menu item. 


MENU_CENTER 


boolean 


If TRUE, all string items in the menu will be centered. Default: FALSE 


MENU_CLI ENT_DAT A 


caddr_t 


For client’s use. 


MENU_COLUMN_MAJOR 


boolean 


If TRUE, string items in the menu will be sorted in column-major 
order (like ls(l)) instead of row-major order. Default: FALSE 


MENU_CLI ENT_DAT A 


caddr_t 


For client’s use. 


MENU_DESCEND_FIRST 


(no value) 


For menu f ind ( ) . If given, search will 
be depth first, else search will be "deferred". 


MENU_DEFAULT 


int 


Default menu item as a position. 


MENU_DEFAULT_ITEM 


Menu_item 


Default menu item as opaque handle. 


MENU_DEFAULT_SELECTION 


enum 


Either MENU_SELECTED or MENU_DEFAULT. 


MENU_FIRST_EVENT 


Event * 


The event which was initially passed into 
menu show(). Get only. 

(Note that the event’s contents can be modified.) 


MENU_FONT 


Pixfont * 


Menu’s font. 


MENUGENPROC 


(procedure) 


Client’s function called to generate the menu. 

Menu gen_proc(m, op) 

Menu m; 

Menu generate op; 


MENU_GEN_PULLRIGHT_IMAGE 


Pixrect *, gen proc 


Create image menu item with 
generate proc for pullright. Set only. 


MENU_GEN_PULLRIGHT_I TEM 


char *, gen proc 


Create string menu item with 
generate proc for pullright. Set only 


MENU_IMAGE__ITEM 


Pixrect *, value 


Create image menu item with value. Set only. 
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Table 19-15 Menu Attributes — Continued 



Attribute Value Type Description 



MENU_ IMAGES list of Pixrect * Create multiple image menu items. Set only. 



MENU_INITIAL_SELECTION 


enum 


Either MENU SELECTED or MENU_DEFAULT. 


MENU_INITIAL_SELECTION_EXPANDED boolean 


If TRUE, when the menu pops up, it 
automatically expands to select the initial selection. 


MENU INI TI AL_SELECTION_SELECTED boolean 


If TRUE, menu comes up with its initial 
selection highlighted. If FALSE, menu comes 
up with the cursor "standing off' to the left. 


MENU_INSERT 


int, Menu_item 


Insert new item after nth item. Set only. 


MENU_INSERT_I TEM 


Menu_item, Menu. 


.item The item given as the second value is inserted 
after the one given as the first value. Set only. 


MENU_ITEM 


avlist 


Create a menu item inline — avlist same as for 
menu create item(). Set only. 


MENU_JUMP_AFTER_NO_SELECTION 


boolean 


If TRUE, cursor jumps back to its 
original position after no selection made. 


MENU_JUMP_AFTER_SELECTION 


boolean 


If TRUE, cursor jumps back to its 
original position after selection made. 


MENU_L AS T__EVENT 


Event * 


The last event read by the menu. Get only. 
Note that the event’s contents can be modified. 


MENU_LEFT_MARGIN 


int 


For each string item, margin in addition to 
MENU MARGIN on left between menu’s 
border and text. Default: 16. 


MENU_MARGIN 


int 


Margin in pixels around menu items. Default: 1. 


MENU_NCOLS 


int 


Number of columns in menu. 


MENU_NITEMS 


int 


Get only; returns the # of items in the menu. 


MENU_NROWS 


int 


Number of rows in menu. 


MENU_NOTIFY_PROC 


(procedure) 


Client’s function called when the user selects 
a menu item. 

caddr t notify proc(m, mi) 

Menu m; 

Menu item mi; 
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Table 19-15 Menu Attributes — Continued 



Attribute 


Value Type 


Description 


MENU_NTH_ITEM 


int 

starting from 1 . 


Get only; returns nth menu item, n is counted 


MENUPARENT 


Menu_item 


The menu item for which the menu is a pullright. Get only. 


MENU_PULLRIGHT_DELTA 


int 


Number of pixels the user must move the cursor 
to the right to cause a pullright menu to pop up. 
Default: 999 9. 


MENU_PULLRIGHT_IMAGE 


Pixrect *, Menu 


Create image menu item with pullright. Set only. 


MENU_PULLRIGHT_I TEM 


char *, Menu 


Create string menu item with pullright. Set only. 


MENU_REMOVE 


int 


Remove the nth item. Set only. 


MENU_REMOVE_ITEM 


Menu_item 


Remove the specified item. Set only. 


MENU_REPLACE 


int, Menu_item 


Replace nth item with specified item. Set only. 


MENU_REPLACE_ITEM 


Menu_item, Menu_item The item given as first value is replaced 
with the one given as the second value 
in the menu (the old item is not replaced 
in any other menus it may appear in). Set only. 


MENU_RIGHT_MARGIN 


int 


For each string item, margin in addition to 
MENU_MARGIN on right 
between menu’s border and text. 


MENU_S ELECTED 


int 


Last selected item, as a position in menu. 


MENU__SELECTED_ITEM 


Menu_item 


Last selected item, as the item’s handle. 


MENU_S H ADOW 


Pixrect * 


Pattern for the shadow to be painted behind 
the menu. If 0, no shadow is painted. 
Predefined shadow pixrects you can use: 
menu_gray25 pr, menu_gray50 pr, 
and menu gray75 pr. 


MENU_STAY_UP 


boolean 


If TRUE the first click of the Menu button puts up the menu, the 
second takes it down; in between, the menu stays up. Default: FALSE 


MENU_STRINGS 


list of char * 


Create multiple string menu items. Set only. 


MENU_STRING_ITEM 


char *, value 


Create string menu item with value. Set only. 
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Table 19-15 Menu Attributes — Continued 
Attribute Value Type Description 

MENU_TI TLE_IMAGE Pixrect * Create image title item. Set only. 

MENU__TTTLE_ITEM char* Create string title item. Set only. 

MENU_TYPE enum Get only; returns MENU MENU. 

MENU VALID RESULT boolean Tells whether a zero return value represents a legitimate value. 
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Table 19-16 


Menu Item Attributes 




Attribute 


Value Type 


Description 


MENU_ACT I ON_IMAGEf 


Pixrect *, action proc 


Modifies appropriate fields in item. Set only. 


MENU_ACTION_ITEMf 


char *, action proc 


Modifies appropriate fields in item. Set only. 


MENU_ AC T I ON_PROC 


(procedure) 


Client’s function called after item has been selected: 
caddr_t action proc (menu, menu item) 
Menu menu 

Menu_item menu item 


MENU_APPEND_ITEMf 


Menu_item 


Append item to end of menu. Set only. 


MENU_BOXEDf 


boolean 


If TRUE, a single-pixel box will be drawn around the item. 


MENU_CENTERt 


boolean 


If TRUE, the menu item will be centered on its row in the menu. 
Only meaningful for menu strings. 


MENU_CLI ENT_DAT Af 


caddr_t 


For use by the client. 


MENU_FEEDBACK 


boolean 


If FALSE, item is never inverted and is not selectable. 


MENU_FONTf 


Pixfont * 


Item’s font. 


MENU_GEN_PROCf 


(procedure) 


Client’s procedure called to generate the item. 


MENU_GEN_PROC_IMAGE 


Pixrect *, (procedure) 


Modifies appropriate fields in item. Set only. 


MENU_GEN_PROC_ITEM 


char *, (procedure) 


Modifies appropriate fields in item. Set only. 


MENU_GEN_PULLRIGHT 


generate proc 


Generate proc for the item’s pullright. 


MENU_GEN_PULLRIGHT_IMAGEf 


Pixrect *, (procedure) 


Modifies appropriate fields in item. Set only. 


MENU_GEN_PULLRIGHT_ITEMt 


char *, gen proc 


Modifies appropriate fields in item. Set only. 


MENU_ IMAGE 


Pixrect * 


Item’s image. 


MENU_IMAGE_ITEMf 


char *, action proc 


Modifies appropriate fields in item. Set only. 


MENU_IN ACTIVE 


boolean 


If TRUE, item is grayed out and not selectable. 



f Many of the attributes in this table appeared in the previous table. Menus and menu items have many attributes in common. Attributes marked with 
“f ” are also valid for menus, although the effect of the attribute may differ. 
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Table 19-16 Menu Item Attributes — Continued 



Attribute 


Value Type 


Description 


MENU_INVERT 


boolean 


If TRUE, item’s display is inverted. 


MENU_LEFT_MARGINf 


int 


Margin in addition of MENU MARG I N on left between 
menu’s border and text. 


MENUMARGINf 


int 


Margin in pixels around the item. 


MENU^PARENTf 


Menu 


The menu containing the item. 


MENU_PULLRIGHT 


Menu 


Item’s pullright menu. 


MENU_PULLRIGHT_IMAGEf 


Pixrect *, Menu 


Modifies appropriate fields in item. Set only. 


MENU_PULLRIGHT_ITEMf 


char *, Menu 


Modifies appropriate fields in item. Set only. 


MENU_RELEASE 


(no value) 


The item will be automatically destroyed when its parent 
menu is destroyed (default for items created inline). 


MENU_RELEASE_IMAGE 


(no value) 


The string or pixrect associated with the item will be 
freed when the item is destroyed. 


MENU_RIGHT_MARGINf 


int 


Margin in addition of MENU MARGI N on right between 
menu’s border and text. 


MENU_S ELECT EDf 


boolean 


If TRUE, the item is currently selected. 


MENU_STRINGf 


char * 


Item’s string. 


MENU_STRING_ITEMf 


char *, value 


Modifies appropriate fields in item. Set only. 


MENU TYPEf 


enum 


Get only, returns MENU ITEM. 


MENU_VALUE 


caddrj 


Item’s value. 
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Table 19-17 Menu Functions 



£ 



Definition 




Description 


Menu 

menu create (attributes ) 

<attribute-list> attributes; 




Creates and returns the opaque handle for a walking menu. 


Menu_item 

menu create item ( attributes ) 
<attribute-list> attributes; 




Creates and returns the opaque handle for a single item 
within a walking menu. 


void 

menu destroy (menu object) 

<Menu or Menujtem > menu object; 




Destroys a menu or menu item. 


void 

menu destroy with proc(menu object 
<Menu or Menu_item> menu ob j ect ; 
void ( *destroy_proc) ( ) ; 


, destroy proc) 


The function supplied as destroy proc is called before 
the menu or menu item is destroyed. Arguments: 
destroy proc(menu object, type) 

<Menu or Menu_item> menu object; 

Menu attribute type; 
type is MENU_MENU for menus, MENU ITEM for items. 


Menu item 

menu find(menu, attributes) 
Menu menu; 

<attribute-list> attributes; 




Returns the first menu item in menu meeting the criteria 
specified in attributes. 


caddr t 

menu get(menu object, attribute[, 
<Menu or Menu_item> menu object; 
Menu attribute attributes; 
caddr t optional arg; 


optional arg] ) 


Retrieves the value for an attribute of a menu or menu item. 


int 

menu set (menu object, attributes) 
<Menu or Menu_item> menuob j ect ; 
<attribute-list> attributes; 




Sets the value of one or more attributes for a menu or menu, 
item, attributes is a null-terminated attribute list. 


caddr t 

menu show(menu, window, event, 0) 
Menu menu; 

Window window; 

Event *event; 




Displays the menu, gets a selection from the user, and, by 
default, returns the value of the item the user has selected, 
window is the handle of the window over which the menu 
is displayed; event is the event which causes the menu to 
come up. The final argument is currently ignored. 
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Table 19-17 Menu Functions — Continued 



Definition 


Description 


caddr t menu show using fd(menu, fd, event) 




Menu menu; 


Provided for compatibility with SunWindows 2.0. Allows 


int fd; 

Event *event; 


you to display a menu within a window using the windowfd. 


caddr_t 


Predefined notify proc which, if given as the value for 


menu return item(menu, menu_item) 


MENU_NOTIFY_PROC, causes menu_show( ) to return 


Menu menu; 

Menu item menu_item; 


the handle of the selected item, rather than its value. 


caddr t 


menu return_value (menu, menu_item) 


Default notify proc for menus. Causes me n u s how ( ) 


Menu menu; 

Menu item menu item; 


to return the value of the selected item. 
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Table 19-18 Notifier Functions 



Definition 


Description 


Notify value 

notify_default_wait3 (client , pid, status, rusage) 
Notify client client; 
int pid; 

union wait *status; 

struct rusage *rusage; 


Predefined function you can register with the Notifier via the 
notify_set_wait3_func ( ) call. Causes the required 
housekeeping to be performed on the process identified by pid 
when it dies. See the wa i t(2) man page for details of the 
wait and rusage structures. 


Notify_error 
notify dispatch() 


Provided to allow programs which are not notification-based to 
run in the SunView environment. Called regularly from within 
the application’s main loop to allow the Notifier to go once 
around its internal loop and dispatch any pending events. 


Notify error 
notify do dispatch() 


Called once, before the application’s main loop. Enables 
“implicit dispatching,” in which the Notifier dispatches 
events from within calls to read(2) or select(2). 


void 

Notify flush pend ing ( ncl ient ) 
Notify client nclient; 


Notifier removes client and flushes requests for it 


Notify error 

notify interpose destroy func(client, destroy func) 
Notify client client; 

Notify func destroy func; 


Interposes destroy f unc ( ) in front of 
client’s destroy event handler. 


Notify error 

notify interpose event func (client, 

event func, type) 
Notify client client; 

Notify_func event_func; 

Notify event type type; 


Interposes event f unc ( ) in front of 
cl ient ’s event handler. 


Notify error 

notify itimer value ( cl ient , which, value) 
Notify client client; 

int which; 

struct itimerval *value; 


Returns the current state of an interval timer for cl ient in the 
structure pointed to by value. The which parameter 
is either I TIMER REAL or ITIMER_VIRTUAL. 


Notify value 

notify next destroy func(client, status) 
Notify client client; 

Destroy status status; 


Calls the next destroy event handler for client, 
status returns DESTROY_PROCESS_DEATH, 
DESTROY CHECKING, or DESTROY_CLEANUP. 
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Table 19-18 Notifier Functions — Continued 





Definition 


Description 


Notify value 






notify next_event_ 


func(client, event, arg, type) 




Notifyclient 


client ; 


Calls the next event handler for client. 


Event 


*event ; 




Notify arg 


arg; 




Notify event type type; 




Notify error 




Prevents the Notifier from dispatching events from within the 


notify no dispatch() 


call to read(2) or select(2). 


void 




Analogous to the UNIX perror(3) system call. 


notify perror(s) 




s is printed to stderr, followed by a terse description of 


char *s; 




notify errno( ). 


Notify func 




Registers destroy func ( ) with the Notifier. 


notify set destroy func(client, destroy func) 


destroy func () will be called when a 


Notify client 


client ; 


destroy event is posted to client or when the process 


Notify func 


destroy func; 


receives a SIGTERM signal. 


Notify func 




Registers the exception handler exception func ( ) 


notify set exception func(client, exception func. 


f d ) with the Notifier. The only known devices that generate 


Notify client 


client ; 


exceptions at this time are stream-based socket 


Notif y_f unc 


exception_f unc ; 


connections when an out-of-band byte is available. 


int 


fd; 




Notify func 






notify set input func(client, input func, fd) 


Registers input func() with the Notifier. 


Notify client 


client ; 


input func() will be called whenever 


Notify_f unc 


input func; 


there is input pending on f d. 


int 


fd; 




Notify func 






notify set_itimer 


func(client, itimer func, which 


Registers the timeout event handler it imer f unc ( ) 




value, ovalue) 


with the Notifier. The semantics of which, value 


Notify client 


client ; 


and ovalue parallel the arguments to setitimer 


Notify func 


itimer func; 


(see the getitimer manual page). 


int 


which; 


which is either ITIMER_REAL or ITIMERJVIRTUAL. 


struct itimerval *value, *ovalue; 
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Table 19-18 Notifier Functions — Continued 



Definition 




Description 


Notify func 

notify set signal_func(client , 

signal , 

Notify client client; 

Notify_func signal__ 

int signal; 

Notify signalmode when; 


signal 
when ) 

func ; 


f unc , 


Registers the signal event handler signal func ( ) with 
the Notifier. signal_func() willbecalled whenever 
signal is caught by the Notifier. when can be either 
NOTIFY SYNC or NOTIFY_ASYNC. 








Calling notify_set_signal_f unc ( ) with a NULL in the 
place of the sign a If unc ( ) turns off checking for that 
signal for that client. 


Notif y_error 
notifystart ( ) 






Begins dispatching of events by the Notifier. 


Notif y_error 
notif y_stop ( ) 






Terminates dispatching of events by the Notifier. 


Notif y_func 

notify set output func(client, 
Notify_client client; 
Notify func output func; 

int fd; 


out.put_ 


func, fd) 


Registers output_f unc ( ) with the Notifier. 
output f unc ( ) will be called whenever 
output has been completed on f d. 


Notify func 

notify set wait3_func ( client , 
Notify client client; 
Notify func wait3 func; 

int pid; 


wait3 func, pid) 


Registers the function wait3 func() with the Notifier. 
The registered function will be called after the child 
process identified by pid dies. To do the minimum 
processing, register the predefined function 
notify default wait3(). 


Notify error 






Called from within a destroy event handler when status 



not ify_veto_des troy (client ) is DESTROY CHECKING and the application does not 

Notifyclient client; want to be destroyed. 
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Attribute 


Value Type 


Description 


PANEL_ACCEPT_KEYSTROKE 


boolean 


If TRUE, keystroke events are passed 

to the panel’s PANEL BACKGROUND PROC. Default: FALSE. 


PANEL BACKGROUND PROC 


(procedure) 


Event handling procedure called when an 
event falls on the background of the panel. Form: 
background proc (panel, event) 
Panel panel 
Event *event 


PANEL_BLI NK_CARET 


boolean 


If TRUE, the caret blinks. Default: setting of Blink_caret in the Text 
category of def aultsedit. 


PANEL_CARET_ITEM 


Panel_item 


Text item which currently has the caret. 
Default: first text item. 


PANEL_EVENT_PROC 


(procedure) 


Event handling procedure for panel items. 

Sets the default for subsequent items created in panel. Form: 

event proc (item, event) 

Panel item item 
Event *event 


PANEL_FIRST_ITEM 


Panel_item 


First item in the panel. Get only. 


PANEL_I TEM_X_G AP 


int 


Number of x-pixels between items. Default: 10. 


PANEL_I TEM_Y_GAP 


int 


Number of y -pixels between items. Default: 5. 


PANEL_LABEL_BOLD 


boolean 


If TRUE, item’s label is rendered in bold. 

Sets the default for subsequent items created in panel. Default: FALSE. 


PANEL_LAYOUT 


Panel_setting 


Layout of item’s value relative to the label. 

PANELJHORIZONTAL (default) or PANEL__VERT ICAL. 


PANEL SHOW MENU 


boolean 


If TRUE, the menu for the item is enabled. 

Sets the default for subsequent items created in panel. 
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Table 19-20 Generic Panel Item Attributes 



Attribute 


Value Type 


Description 


PANEL_ACCEPT_KEYSTROKE 


boolean 


If TRUE, keystroke events are passed to the item’s EVENT PROC. 


PANEL_CLIENT_DATA 


caddr_t 


For application’s use. 


PANELJEVENTPROC 


(procedure) 


Event handling procedure for the item. 


PANEL_ITEM_COLOR 


int 


Index into colormap, sets color for item. 


PANEL_ITEM_RECT 


Rect * 


Enclosing rectangle for the item. Get only. 


PANEL_ITEM_X 


int 


Left edge of item rectangle. If unspecified and label or value positions are 
fixed, then set to min of PANEL_LABEL_X and PANEL_VALUE_X. 
Default: after lowest, rightmost item 


P ANEL_I TEM_Y 


int 


top edge of item rectangle. If unspecified and label or value positions are 
fixed, then set to min of PANEL_LABEL_Y and PANEL_VALUE_Y. 
Default: previous item’s PANEL __ITEM_Y. 


PANEL_LABEL_X 


int 


Left edge of label. If unspecified and value position is fixed, then set to 
left of PANEL VALUE X for horizontal layout, or at PANEL VALUE X 
for vertical layout. Default: PANEL_ITEM_X. 


PANEL_LABEL_Y 


int 


Top edge of label. If unspecified and value position is fixed, then set to 
PANEL_VALUE _Y for horizontal layout, or above PANEL_VALUE Y 
for vertical layout. Default: PANEL ITEM Y. 


PANEL_LABEL_BOLD 


boolean 


If TRUE, item’s label is rendered in bold. Default: FALSE. 


PANEL_LABEL_FONT 


Pixfont * 


Font for PANEL_LABEL_STRING. Default: WIN_FONT. 


PANEL LABEL_I MAGE 


Pixrect * 


Image for item’s label. 


PANEL_LABEL_STRING 


char * 


String for item’s label. 


PANELLAYOUT 


Panel_setting 


Layout of item’s value relative to the label. PANEL HORI ZONTAL 
(default) or PANEL_VERTICAL. 


PANEL_MENU_CHOICE_FONTS 


list of Pixfont * 


Font for each menu choice string. Create, set. Default: WIN FONT. 


PANEL_MENU_CHOICE_IMAGES 


list of Pixrect * 


Image for each menu choice. Create, set. Default: 

PANEL_CHOICE_ IMAGES for choice items, PANEL_LABEL_IMAGE 
for button items, NULL for other items. 


PANEL_MENU_CHOICE_ST RINGS 


list of char * 


String for each menu choice. Create, set. Default: 
PANEL_CHOICE_STRINGS for choice items, NULL for other items. 
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Table 19-20 Generic Panel Item Attributes — Continued 



Attribute 


Value Type 


Description 


PANEL_MENU_CHOICE_VALUES 


list of caddr_t 


The values returned from the item’s menu. Create, set. 


PANEL_MENU_T I TLE_FONT 


Pixfont * 


Font for PANEL_MENU_TITLE_STRING. 


PANEL_MENU_TI TLE_IMAGE 


Pixrect * 


Image for the menu title. 


PANEL_MENU_TITLE_STRING 


char * 


String for the menu title. 


PANEL_NEXT_I TEM 


Panel_item 


Next item in the panel. Get only. 


PANEL_NOTIFY_PROC 


(procedure) 


Function to call when item is selected. Form for button and text items: 

notify proc(item, event) 

Panel_item item; 

Event * event; 

Choice and slider items have an additional parameter for the current value: 

notify proc(item, value, event) 

Panel item item; 
int value; 

Event *event; 

For toggle items, the value parameter is of type uns igned int. 

The type for a text item notify proc is Panel setting. 


PANEL_PAINT 


Panel_setting 


Item’s painting behavior for panel set ( ) calls. One of: 
PANEL_NONE, PANEL_CLEAR, or PANEL_NO_CLEAR. 


PANEL_PARENT_PANEL 


Panel 


The panel which contains the item. 


P ANEL _SHOW_I TEM 


boolean 


Whether or not to show the item. Default: TRUE. 


PANEL_SHOW_MENU 


boolean 


If TRUE, the menu for the item is enabled. 


PANEL_VALUE_X 


int 


Left edge of value. If unspecified and label position is fixed, 
then set to right of PANEL LABEL X for horizontal layout, or 
at PANEL LABEL X for vertical layout. Default: after the label. 


PANEL_VALUE_Y 


int 


Top edge of value. If unspecified and label position is fixed, then set 
to PANEL LABEL Y for horizontal layout, or below 
P AN EL_LABEL_Y for vertical layout. Default: PANEL_LABEL_Y. 
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Table 1 9-2 1 Choice and Toggle Item Attributes 



Attribute 


Value Type 


Description 


PANEL_CHOICE_FONTS 


list of Pixfont * 


Font to use for each choice string. Create, set. 


PANEL_CHOICE_IMAGE 


int, pixrect * 


Image for choice specified by the first argument. 


PANEL_CHOICE_IMAGES 


list of Pixrect * 


Image for each choice. Create, set. 


PANEL_CHOICE_STRING 


int, char * 


String for choice specified by first argument. 


PANEL_CHOICE_STRINGS 


list of char * 


String for each choice. Note that you must specify at 
least one choice — the least you can specify is a single 
null string (PANEL_CHOICE_STRINGS, 0). 

Create, set. 


PANEL_CHOICE_X 


int, int 


Second argument is left edge of choice specified by first 
argument. 


PANEL_CHOICE_XS 


list of int 


Left edge of each choice. Create, set. 


PANEL_CHOICE_Y 


int, int 


Second argument is top edge of choice specified by first 
argument. 


PANEL_CHOICE_YS 


list of int 


Top edge of each choice. Create, set. 


PANEL_CHOICES_BOLD 


boolean 


If TRUE, choices strings are in bold. Default: FALSE. 


PANEL_DISPLAY_LEVEL 


Panel_setting 


How many choices to display. One of PANEL_NONE, 
PANEL CURRENT, or PANEL_ALL. Default: 
PANEL_ALL. 


PANEL_FEEDBACK 


Panel_setting 


Feedback to give when a choice is selected. One of 
PANEL_NONE, PANEL_MARKED, 

PANEL_INVERTED. If PANEL_DISPLAY_LEVEL is 
PANEL CURRENT, default is PANEL NONE, otherwise 
PANEL MARKED. 


PANEL_LAYOUT 


Panel_setting 


Layout of the choices: PANEL HORI ZONTAL (default) 
or PANEL_VERTICAL. 


PANEL_MARK_IMAGE 


int, Pixrect * 


Image to mark choice specified by the first argument 
when it is selected. Default is push-button image: 
<images/panel choice on.pr>. 
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Table 19-21 


Choice and Toggle Item Attributes — Continued 


Attribute 


Value Type 


Description 


PANEL_MARK_IMAGES 


list of Pixrect * 


Image to mark each choice with when selected. Create, 
set only. Default is push-button image: 
<images/panel choice on.pr>. 


PANEL_MARK_X 


int, int 


Second argument is left edge of choice mark specified by 
first argument. 


PANEL_MARK_XS 


list of int 


Left edge of each choice mark. Create, set. 


PANEL_MARK_Y 


int, int 


Second argument is top edge of choice mark specified by 
first argument. 


PANEL_MARK_YS 


list of int 


Top edge of each choice mark. Create, set. 


PANEL_MENU_MARK_IMAGE 


Pixrect * 


Image to mark each menu choice with when selected. 


PANEL_MENU_NOMARK_IMAGE 


Pixrect * 


Image to mark each menu choice with when not selected. 


PANEL_NOMARK_IMAGE 


int, Pixrect * 


Image to mark choice specified by the first argument 
when it is not selected. Default is push-button image: 

<images/panel choice off.pr>. 


PANEL_NOMARK_IMAGES 


list of Pixrect * 


Image to mark each choice with when not selected. 
Create, set. Default is push-button image: 
<images/panel choice off.pr>. 


PANEL_SHOW_MENU_MARK 


boolean 


Show or don’t show the menu mark for each selected 
choice. Default: TRUE. 


PANEL_TOGGLE_VALUE 


int, int 


Value of a particular toggle choice. Second argument is 
value of choice specified by first argument. 


PANEL_VALUE 


int or unsigned 


If item is a choice, value is ordinal position (from 0) of 
current choice. If item is a toggle, value is a bitmask 
indicating currently selected choices (e.g., bit 5 is 1 if 
5th choice selected). 
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Table 19-22 


Slider Item Attributes 




Attribute 


Value Type 


Description 


PANEL_MIN_VALUE 


int 


Minimum value of slider. Default: 0. 


PANEL_MAX_VALUE 


int 


Maximum value of the slider. Default: 100. 


PANEL_NOTI FY_LEVEL 


Panel_setting 


When to call the notify function: PANEL DONE notifies when the 
select button is released, PANEL ALL notifies continuously as the 
select button is dragged. Default: PANEL_DONE. 


PANEL_SHOW_RANGE 


boolean 


Show or don’t show the min and max slider values. Default: TRUE. 


PANEL_SHOW_VALUE 


boolean 


Show or don’t show integer value of slider. Default: TRUE. 


PANEL_SLIDER_WIDTH 


int 


Width of the slider bar in pixels. Default: 100. 


PANEL_VALUE 


int 


Initial or new value for the item, in the range 
PANEL_MIN_VALUE to PANEL_MAX_VALUE. Default: 
PANEL_M I N_V A LUE. 


PANEL_VALUE_FONT 


Pixfont * 


Font to use when displaying the value. 
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Table 19-23 


Text Item Attributes 










Attribute 


Value Type 


Description 


PANEL_MASK_CHAR 


char 


Character used to mask type-in characters. Use the space character 
for no character echo (caret does not advance). Use the null char- 
acter to disable masking. 


P ANEL_NOT I FY_LEVEL 


Panel_setting 


When to call the notify function. One of PANEL NONE, 
PANEL_NON_PRINTABLE, PANEL_SPECIFIED, or 
PANEL_ALL. Default: PANEL_SPECIFIED (see Text 
Notification). 


P AN EL_NO TIFY_STRING 


char * 


String of characters which trigger notification when typed. 

Applies only when PANEL NOTIFY LEVEL is 
PANEL_SPECIFIED. Default: \n\r\t (newline, carriage return 
and tab). 


PANEL_VALUE_STORED_LENGTH 


int 


Max number of characters to store in the value string. Default: 80. 


PANEL_VALUE_DISPLAY_LENGTH 


int 


Max number of characters to display in the panel. Default: 80. 


PANEL_VALUE 


char * 


Initial or new string value for the item. 


PANEL_VALUE_FONT 


Pixfont * 


Font to use for the value string. 
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Table 19-24 Panel Functions and Macros 



Definition 




Description 


panel_accept key (object, event) 
<Panel or Panel_item> ob j ect ; 
Event *event; 


Action function which tells a text item to accept a keyboard event. 
Currently ignored by non-text panel items. 


panel accept menu(object, event) 
<Panel or Panel jtem> object ; 
Event *event; 


Action function which tells an item to display its menu and process 
the user’s selection. 


panel accept preview(object , 
<Panel or Panel jtem> ob j ect ; 
Event *event; 


event ) 


Action function which tells an item to do what it is supposed to do 
when it is selected. This may include completing feedback 
initiated by panel_begin preview(). 


Panel item 

panel advance caret(panel) 
Panel panel; 




Advance the caret to the next text item. If on the last 
text item, rotate back to the first. Returns the new 
caret item, or NULL if there are no text items. 


Panel item 

panel backup caret (panel) 
Panel panel; 




Backup the caret to the previous text item. If on the 
first text item, rotate back to the first. Returns the 
new caret item, or NULL if there are no text items. 


panel begin preview(object , 

< Panel or Panel item > object; 
Event *event; 


event ) 


Action function which tells an item to begin any feedback which 
indicates tentative selection. 


Pixrect * 

panel button image ( panel , string, width, font) 
Panel panel; 
char ^string; 
int width; 

Pixfont *font; 


Creates a standard, button-like image from a string. The string is 
rendered in font, centered within a double-pixel border width 
characters wide. If width is too narrow for the string, the border 
will be expanded to contain the entire string. If font is 0, 
panel’s font is used. 


panel cancel preview (obj ect , 
<Panel or Panel Jtem> obj ect ; 
Event *event; 


event ) 


Action function which tells an item to cancel the feedback initiated 

by panel begin preview(). 


Panel item 

panel create_item(panel , item type, attributes) 
Panel panel; 

<item type> item type ; 

<attribute-list> attributes; 


Creates and returns the opaque handle to a panel item, item type 
is one of: PANEL_MESSAGE, PANEL_BUTTON, PANEL_CHOICE, 
PANEL_CYCLE, PANEL_TOGGLE, PANEL TEXT or 
PANEL_SLIDER. attributes is a null-terminated attribute list. 
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Table 19-24 Panel Functions and Macros — Continued 



Definition 


Description 


panel default handle event ( object , event) 
<Panel or Panel jtem> ob j ect ; 

Event *event; 


The default event proc for panel items (PANEL EVENT PROC) 
and for the panel’s background (PANEL BACKGROUND PROC). 
Implements the standard event-to-action mapping for the item types. 


panel destroy item(item) 
Panel item item; 


Destroys item. 


panel each_item(panel , item) 
Panel panel; 

Panel item item; 


Macro to iterate over each item in a panel. The corresponding macro 
panel end each closes the loop opened by 
panel each item(). 


Event * 

panel event (panel, event) 
Panel panel; 

Event *event; 


Translates the coordinates of event from the space of the panel 
subwindow to the space of the logical panel 
(which may be larger and scrollable). 


caddr t 

panel get(item, attribute[, optional arg]) 
Panel item item; 

Panel attribute attribute; 
Panel_attribute optional arg; 


Retrieve the value of an attribute for item, optional arg is 
used for a few attributes which require additional information, 
such as PANEL_CHOICE_IMAGE, PANEL_CHOICE_STRING, 
PANEL_CHOICE_X, PANEL_CHOICE_Y, 

PANEL_MARK_X, PANEL_MARK_Y, PANEL_TOGGLE__VALUE. 


caddr t 

panel get value(item) 
Panel_item item; 


A macro, defined as: 

panel_get (item, PANEL_VALUE) 


panel paint(panel object, paint behavior) 
<Panel item or Panel> panel object; 

Panel setting paint behavior; 


Paints an item or an entire panel, pa i nt behavior can be either 
PANEL_CLEAR or PANEL NO _CLEAR. PANEL CLEAR causes 
the area occupied by the panel or item to be cleared prior to painting. 


panel set (item, attributes) 
Panel item item; 
<attribute-list> attributes; 


Sets the value of one or more panel attributes, 
attributes is a null-terminated attribute list. 


panel set value(item, value) 
Panel item item; 
caddr_t value; 


A macro, defined as: 

panel_set ( item, PANEL_VALUE, value, 0) 


Panel setting 

panel text notify (item, event) 
Panel item item 
Event * event 


Default notify procedure for panel text items. Causes caret 
to advance on CR or tab, caret to backup on shift-CR or shift-tab, 
printable characters to be inserted into item's value, 
and all other characters to be discarded. 
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Table 19-24 


Panel Functions and Macros — Continued 


Definition 




Description 


panel_update preview (object, 
<Panel or Panel _item> ob j ect ; 
Event *event; 


event ) 


Action function which tells the item to update its previewing 
feedback (e.g. redraw the slider bar for a slider item). 


panel update scrolling size(panel) 
Panel panel; 


Updates the scrollbar’s notion of the panel’s size, 
so the scrollbar’s bubble will be the correct size. 


Event * 

panel_window_event( panel, event) 
Panel panel; 

Event *event; 


Translates the coordinates of event to the space of the panel 
subwindow from the space of the logical panel 
(which may be larger and scrollable). 
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Table 19-25 Pixwin Drawing Functions and Macros 



" 


Definition 


Description 


pw batch (pw, n) 

Pixwin *pw ; 

Pw batch_type n; 


Tells the batching mechanism to refresh the screen every 
n display operations. 


pwbatch off(pw) 
Pixwin *pw ; 


A macro to turn batching off in pw. 


pw batch on(pw) 
Pixwin *pw ; 


A macro to turn batching on in pw. 


pw batchrop(pw, dx, dy , op, items, n) 
Pixwin *pw ; 

int dx, dy, op, n; 

struct pr_prpos items [] ; 


See the Pixrect Reference Manual for a full explanation 
of this function. 


pw_char(pw, x, y, op, font, c) 
Pixwin *pw ; 
int x, y, op; 

Pixfont *font; 
char c; 


Writes character c into pw using the rasterop op. 
The left edge and baseline of c will be written at 
location (x, y). 


pw close (pw) 

Pixwin *pw; 


Frees any dynamic storage associated with pw, 
including its retained memory pixrect, if any. 


pw copy(dpw, dx, dy, dw, dh, 
op, spw, sx, sy) 

Pixwin *dpw, *spw; 

int op, dx, dy, dw, dh, sx, sy; 


Copies pixels from spw to dpw. Currently spw and 
dpw must be the same. This routine will cause problems if 
spw is obscured. 


int 

P w _get ( pw , x, y) 
Pixwin *pw; 
int x, y; 


Returns the value of the pixel at (x , y) in pw. 


int 

pw get region rect(pw, r) 
Pixwin *pw; 

Rect *r; 


Retrieves the rectangle occupied by the region pw 
into the rect pointed to by r. 
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Table 19-25 Pixwin Drawing Functions and Macros — Continued 





Definition 




Description 


pw line(pw, xO, yO, xl , yl , brush, 
Pixwin *pw ; 

int xO, yO, xl, 

struct pr brush *brush; 

struct pr texture *tex; 


tex, op) 

yl/ op; 


Draws a solid or textured line between two points with a 
“brush” of a specified width. 


pw lock(pw, r) 
Pixwin *pw; 
Rect *r; 






Acquires a lock for the user process making the call, 
r is the rectangle in pw’s coordinate system 
that bounds the area to be affected. 


pw pfsysclose() 






Closes the system font opened with pw pf sysopen ( ) . 


Pixfont * 
pw pf sysopen ( ) 






Opens the system font. 



pw_polygon_2 ( pw, dx, dy, nbds , npts. 



vlist, op, spr, sx, sy) 

Pixwin *pw; 

int dx, dy, nbds, op, sx, sy; Draws a polygon in pw. 

int npts [ ] ; 

struct pr_pos *vlist; 

Pixrect *spr; 



pw_polyl ine ( pw, dx, dy, npts, 

ptlist, mvlist, brush, tex, op) 



Pixwin 




*pw ; 




int 




dx, dy, npts, op; 


Draws multiple lines of a specified width and texture in 


struct 


pr pos 


*ptlist ; 


pw. 


u char 




*mvlist ; 




struct 


pr brush 


*brush; 




struct 


pr texture 


*tex; 





pw polypoint (pw, dx, dy, npts, ptlist, op) 

Pixwin *pw; ... 

Draws an array of npts points in the pixwin pw 

int dx, dy, npts, op; 

struct prpos *ptlist; 



pw_put(pw, x, y, value) 

Pixwin *pw; Draws a pixel of value at (x, y) in pw. 

int x, y, value; 
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Table 19-25 Pixwin Drawing Functions and Macros — Continued 



Definition 


Description 


pw read(pr, dx, dy, dw, dh, op, pw, sx , sy) 
Pixwin *pw; 

int op, dx, dy, dw, dh, sx, sy; 

Pixrect *pr; 


Reads pixels from the pixwin pw starting at offset (sx, 
sy), using rasterop op. The pixels are stored in the rec- 
tangle (dx, dy, dw, dh) in the pixrect pointed to by pr. 


Pixwin * 

pw region(pw, x, y, width, height) 
Pixwin *pw ; 
int x, y, w, h; 


Creates a new pixwin refering to an area within the existing 
pixwin pw. The origin of the new region is given by (x , 
y), the dimensions by width and height. 


pw replrop(pw, dx, dy, dw, dh, 
op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 


Replicates a pattern from a pixrect into a pixwin. 


pw reset (pw) 

Pixwin *pw ; 


Macro which sets pw’s lock count to 0 and releases its lock. 


pw rop(pw, dx, dy, dw, dh, 
op, sp, sx, sy) 

Pixwin *pw; 

Pixrect *sp; 

int dx, dy, dw, dh, op, sx, sy; 


Performs the rasterop op from the source pixrect 
sp to the destination pixwin pw. 


int 

pw set region rect(pw, r, use same pr) 
Pixwin *pw; 

Rect *r; 

unsigned int use same pr; 


The position and size of the region pw are set to the rect 
*r. 

If use same pr is 0 a new retained pixrect is allocated 
for the region. 


pw show(pw) 

Pixwin *pw; 


Macro to refresh the screen while batching, without affect- 
ing the batching mode. 


pw stencil(dpw, dx, dy, dw, dh, op, 

stpr, stx, sty, spr, sx, sy) 

Pixwin *dpw; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 

Pixrect *stpr, *spr; 


Like pw write ( ) , except that the source pixrect spr is 
written through the stencil pixrect stpr, which functions 
as a spatial write enable mask. The raster operation op is 
only applied to destination pixels where the stpr is non- 
zero; other destination pixels remain unchanged. 
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Table 19-25 Pixwin Drawing Functions and Macros — Continued 


Definition 


Description 


pw_text(pw, x, y , op, font, s) 
Pixwin *pw; 
int x, y, op; 

Pixfont *font; 
char *s; 


Writes the string s into pw using the rasterop op. 

The left edge and baseline of the first character in s will 
appear at coordinates (x, y). 


pw traprop(pw, dx, dy, t, op, pr, sx, sy) 
Pixwin *pw; 

struct pr_trap t; 

Pixrect *pr; 

int dx, dy, op, sx, sy; 


Like pw rop ( ) , but operating on a trapezon rather than a 
rectangle. 


pw_ttext(pw, x, y, op, font, s) 
Pixwin *pw; 
int x, y, op; 

Pixfont *font; 
char *s; 


Like pw text ( ) except that it writes “transparent” text, 
i.e. it writes the shape of the letters without disturbing the 
background behind the letters. 


pw_unlock (pw) 

Pixwin *pw; 


Decrements the lock count for pw. If the lock count goes 
to 0, the lock is released. 


pw_vector (pw, xO, yO, xl, yl, op, value) 
Pixwin *pw ; 

int op, xO , yO, xl, yl, value; 


Draws a vector of pixel value from (xO, y0)to(xl, 
yl)in pw using rasterop op. 


pw write(pw, dx, dy, dw, dh, 
op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 


Writes pixels to pw in the rectangle defined by dx, dy, 
dw, dh, using rasterop op. Pixels to write are taken from 
the rectangle with its origin at sx, sy in the source pix- 
rect pointed to by pr. 


pw writebackground (pw, dx, dy, dw, dh, op) 
Writes pixels with value zero into pw using 
T} 

Pixwin *pw; 

int dx, dy, dw, dh, op; 


T{ 

the rasterop op. 

xd, yd, width and height specify the rectangle in 
pw which is affected. 
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Table 19-26 Pixwin Color Manipulation Functions 



Definition 




Description 


pw blackonwhite(pw, min, max) 




Sets the foreground to black, the background to white, for pixwin 


Pixwin *pw ; 




pw. min and max should be the first and last entries, respectively. 


int min, max; 




in pw’s colormap segment. 


pw_cyclecolormap ( pw, cycles, index, 


count) 


Rotates the portion of pw’s colormap segment starting at index 


Pixwin *pw ; 




for count entries, rotating those entries among themselves 


int cycles, index, count; 




cycles times. 


pw dbl access (pw) 




Resets the window’s data structure so that the first frame will be ren- 


Pixwin *pw; 




dered to the background. 


pw_dbl flip(pw) 




Allows you to flip the display. 


Pixwin *pw; 






pw dbl get(pw, attribute) 




Retrieves the value of the specified attribute. 


Pixwin *pw; 






Pw dbl attribute attribute; 






pw_dbl release () 




Signifies the end of double-buffering by the window associated with 


Pixwin *pw; 




the pixwin. 


pw dbl set(pw, attributes) 
Pixwin * pw ; 

<attribute-list> attributes; 




Sets the pixwin hardware double-buffering attributes in attri- 
butes. 


pw_getattributes (pw, planes) 




Retrieves the value of pw’s access enable mask 


Pixwin *pw; 
int *planes; 




into the integer addressed by planes. 


pw getcmsname(pw, cmsname) 




Copies the colormap segment name of pw into cmsname. 


Pixwin *pw; 

char cmsname [ CMS_NAMESI ZE] ; 






pw_getcolormap (pw, index, count. 




Retrieves the state of pw’s colormap. The count elements 


red, green, blue) 




of the pixwin’s colormap segment starting at index 


Pixwin *pw; 




(0 origin) are loaded into the first count values in the 


int index, count; 

unsigned char red f ] , green [] , 


blue [ ] ; 


three arrays. 
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Table 19-26 Pixwin Color Manipulation Functions — Continued 



Definition 


Description 


pw_getdef aultcms ( cms , map) 

struct colormapseg *cms; 
struct cms map *map; 


Copies the data in the default colormap segment into 

the data pointed to by cms and map. Before the call, the byte pointers 

in map should be initialized to arrays of size 256. 


pw_putattributes (pw, planes) 
Pixwin *pw; 
int *planes; 


Sets the access enable mask of pw. Only those bits of the pixel 
corresponding to a 1 in the same bit position of *planes will be 
affected by pixwin operations. 


pw putcolormap (pw, index, count, 
red, green, blue) 

Pixwin *pw ; 

int index, count; 

unsigned char red [ ] , green [] , blue[]; 


Sets the state of pw’s colormap. The count elements of the 
pixwin’s colormap segment starting at index (0 origin) are loaded 
from the first count values in the three arrays. 


pw_reversevideo ( pw, min, max) 
Pixwin *pw ; 
int min, max; 


Reverses the foreground and background colors of pw 
min and max should be the first and last entries, 
respectively, in the colormap segment. 


pw setcmsname(pw, cmsname) 

Pixwin *pw; 

char cmsname [ CMS_NAMES I ZE] ; 


cmsname is the name that pw will call its window’s 

colormap segment. This call resets the colormap segment to NULL. 


pw whiteonblack ( pw , min, max) 
Pixwin *pw; 
int min, max; 


Sets the foreground to white, the background to black, for pw. 
min and max should be the first and last entries, respectively, in the 
colormap segment. 
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Table 19-27 Scrollbar Attributes 



Attribute 


Value Type 


Description 


SCROLL ABSOLUTE_CURSOR 


Cursor 


Cursor to display on middle button down. 

Default: Right triangle if vert., down triangle if horiz. 


SCROLL ACT IVE_CURSOR 


Cursor 


Cursor to display when cursor is in bar rect. 

Default: Right arrow if vertical, down arrow if horiz. 


SCROLL_ADVANCED_MODE 


boolean 


Whether notify proc reports all nine motions. Default: FALSE. 


SCROLL_BACKWARD_CURSOR 


Cursor 


Cursor to display on right button down. 

Default: up arrow if vertical, left arrow if horiz. 


SCROLL_BAR_COLOR 


Scrollbar_setting 


Color of bar, SCROLL_GREY (default) or SCROLL_WHITE. 


SCROLL_BAR_DISPLAY_LEVEL 


Scrollbar_setting 


When bar is displayed. 

SCROLL ALWAYS: always displayed 

SCROLL ACTIVE: only displayed when cursor is in bar rect 

SCROLL_NEVER: never displayed 

Default: SCROLL_ALWAYS. 


SCROLL_BORDER 


boolean 


Whether the scrollbar has a border. 


SCROLL_BUBBLE_COLOR 


Scrollbar_setting 


Color of bubble, SCROLL_GREY (default) or SCROLL_BLACK. 


SCROLL_BUBBLE_DISPLAY_LEVEL 


Scrollbar_setting 


When bubble is displayed. 

SCROLL ALWAYS: always displayed 

SCROLL ACTIVE: only displayed when cursor is in bar rect 

SCROLL NEVER: never displayed 

Default: SCROLL ALWAYS. 


SCROLL BUBBLE_MARGIN 


int 


Margin on each side of bubble in bar. Default: 0. 


SCROLL DIRECTION 


Scrollbar_setting 


Orientation of bar, 

SCROLL VERT ICAL (default) or SCROLL HORIZONTAL. 


SCROLL END_PO I NT_AREA 


int 


The distance, in pixels, from the end of the scrollbar 
that forces a scroll to the beginning (or end) of the file. 
Default: 6. 


SCROLL_FORWARD_CURSOR 


Cursor 


Cursor to display on left button down. 

Default: down arrow if vertical, right arrow if horiz. 


SCROLL_GAP 


int 


Gap between lines. Default: current value of SCROLL MARGIN. 
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Table 19-27 Scrollbar Attributes — Continued 



Attribute 


Value Type 


Description 


SCROLL_HEIGHT 


int 


r height for scrollbar’s rect. 


SCROLL_LAST_VIEW_START 


int 


Offset of view into object prior to scroll. Get only. 


SCROLL_LEFT 


int 


r lef t for scrollbar’s rect. 


SCROLL_LINE_HEIGHT 


int 


Number of pixels from one line to the next. 
Default: 0. 


SCROLL_MARGIN 


int 


Top margin after scroll, if SCR0LL_N0RMALI ZE TRUE. 
Default: 4. 


SCROLL_MARK 


int 


Position (in client units) undo will go to. Initial value: 0. 


SCROLL_NOTIFY_CLIENT 


caddr_t 


Used by Notifier. 


SCROLL_NORMALIZE 


boolean 


Whether the client wants normalized scrolling. Default: TRUE. 


SCROLL_OBJECT 


caddr_t 


Pointer to the scrollable object. 


SCROLL_OBJECT_LENGTH 


int 


Length of scrollable object, in client units. Default: 0. 
(Value must be > 0). 


SC R0LL_P AGE BUTTONS 


boolean 


Whether the scrollbar has page buttons. Default: TRUE. 


SCROLL_PAGE_BUTTON_LENGTH 


int 


Length in pixels of page buttons. Default: 15. 


SCROLL_PAINT_BUTTONS_PROC 


(procedure) 


Procedure which paints page buttons: 






paint_buttons proc ( scrollbar ) 






Scrollbar scrollbar; 






Setting the value to NULL resets it to the default button painting 
procedure. 


SCROLL_PIXWIN 


Pixwin * 


Pixwin for scrollbar to write to. 


SCROLL_PLACEMENT 


Scrollbar_setting 


Placement of the bar. 

SCR0LL WEST: vertical bar on left edge 
SCROLL EAST: vertical bar on right edge 
SCROLL_NORTH: horizontal bar on top edge 
SCROLL SOUTH: horizontal bar on bottom edge 






Default: SCROLLJWEST or SCROLL_NORTH. 


SCROLL_RECT 


Rect * 


Rect for scrollbar, including buttons. 
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Table 19-27 Scrollbar Attributes — Continued 



Attribute 


Value Type 


Description 


SCROLL_REPEAT_TIME 


int 


The interval, in tenths of a second, that scrolling 

repeats in. This attribute is used only for the initial pressing down 

of the mouse. A value of 0 disables repeat scrolling. Default: 10. 


SCROLL_REQUEST_MOTION 


Scroll_motion 


Scrolling motion requested by user. 


SCROLL_REQUEST_OFFSET 


int 


Pixel offset of scrolling request into scrollbar. Default: 0. 


SCROLL JTHICKNESS 


int 


Thickness of bar. Default: 1 4. 


SCROLL_TO_GRID 


boolean 


Whether the client wants scrolling aligned to multiples 
of SCROLL_LINE_HEIGHT. Default: FALSE. 


SCROLL_TOP 


int 


r top for scrollbar’s rect. 


SCROLL_VI EW_LENGTH 


int 


Length of viewing window, in client units. Default: 0. 


SCROLL_VIEW_START 


int 


Current offset into scrollable object (client units). 
(Value must be > 0). Default: 0. 


SCROLL_WIDTH 


int 


r width for scrollbar’s rect. 
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Table 19-28 Scrollbar Functions 



Definition 


Description 


Scrollbar 

scrollbar_create ( attributes ) 
<attribute-list> attributes; 


Creates and returns the opaque handle to a scrollbar. 


int 

scrollbar destroy ( scrollbar ) 
Scrollbar scrollbar; 


Destroys scrollbar. 


caddr t 

scrollbar get ( scrollbar , attribute) 
Scrollbar scrollbar; 

Scrollbar attribute attribute; 


Retrieves the value for an attribute of scrollbar. 


int 

scrollbar set ( scrollbar , attributes) 
Scrollbar scrollbar; 

<attribute-list> attributes; 


Sets the value for one or more attributes of scrollbar, 
attributes is a null-terminated attribute list. 


void 

scrollbar scroll to ( scrollbar , new view start) 
Scrollbar scrollbar; 
long new_view_start ; 


For programmatic scrolling. Effect is as if the user had 
requested a scroll to new view start in the subwin- 
dow to which scrollbar is attached. 


int 

scrollbar paint ( scrol lbar ) 
Scrollbar scrollbar; 


Paints those portions of scrollbar 
(page buttons, bar proper, and bubble) 
which have been modified since they were last painted. 


int 

scrollbar paint clear (scrollbar) 
Scrollbar scrollbar; 


Clears and repaints all portions of scrollbar. 


int 

scrollbar clear bubble ( scrollbar ) 
Scrollbar scrollbar; 


Clears the bubble in scrollbar. 


int 

scrollbar_paint bubble (scrollbar ) 
Scrollbar scrollbar; 


Paints the bubble in scrollbar. 
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Table 19-29 Text Subwindow Attributes 



Attribute 


Value Type 


Description 


TEXTSW_ADJUST_IS_PENDING_DELETE 


boolean 


When TRUE, adjusting a selection causes the selection to be 
pending-delete. Default: FALSE. 


TEXTSW_AGAIN_RECORDING 


boolean 


When FALSE, changes made to the textsw are not repeated when user 
invokes AGAIN. By disabling when not needed (e.g. for program- 
driven error logs) you can reduce memory overhead. Default: TRUE. 


TEXTSW_AUTO_INDENT 


boolean 


When TRUE, a new line is automatically indented to match 
the previous line. Default: FALSE. 


TEXTSW_AUTO_SCROLL_BY 


int 


Number of lines to scroll when type-in moves insert point 
below the view. Default: 1. Create, get. 


TEXTSW_BLINK_CARET 


boolean 


Determines whether the caret blinks. Default: TRUE. 


TEXTSW_B ROWSING 


boolean 


When TRUE, prevents editing of the displayed text. If another 
file is loaded in, browsing stays on. Default: FALSE. 


TEXTSW_CHECKPOINT_FREQUENCY 


int 


Number of edits between checkpoints. Set to 0 to 
disable checkpointing. Default: 0. 


TEXTSW_CLIENT_DATA 


char * 


Pointer to arbitrary client data. Default: NULL. 


TEXTSW_CONFIRM_OVERWRITE 


boolean 


A request to write to an existing file will require user 
confirmation. Default: TRUE. 


TEXTSW_CONTENTS 


char * 


Contents of text subwindow. Default: NULL. 

For create and set, specifies the initial contents for non-file textsw. 

Get needs additional parameters: 

window get ( textsw, TEXTSW CONTENTS, pos, buf, buf_len) 
Return value is next position to read at. 

buf [ 0...buf Ten- 1 ] is filled with the characters from textsw 
beginning at index pos, and is null -terminated only if there 
were too few characters to fill the buffer. 


TEXTSW CON TROL_CH A RS_USE_FONT 


boolean 


If FALSE, control characters always display as an 
up arrow followed by a character, instead of whatever 
glyph is in the current font. Default: FALSE. 


TEXTSW_DISABLE_CD 


boolean 


Stops textsw from changing current working directory 
(and grays out the associated items in the menu). 
Default: FALSE. 
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Table 19-29 Text Subwindow Attributes — Continued 

Attribute Value Type Description 

TEXTSW DISABLE LOAD boolean Prevents files being loaded into the textsw (and grays out 

the associated items in the menu). Default: FALSE. 

TEXTSW EDIT COUNT int Monotonically incrementing count of the number of edits 

made to the textsw. Get. 

TEXTSW FILE char * File to load. Default: NULL. Create, set. 

TEXTSW FILE CONTENTS char * initializes the text subwindow contents 

from a file yet still edits the contents in memory. 

TEXTSW_FIRST int Zero-based index of first displayed character. 

TEXTSW_FIRST_LINE int Zero-based index of first displayed line. 

TEXTSW_HISTORY_LIMIT int Number of user action sequences that can be undone. 

Default: 50. Create, get. 

TEXTSW_IGNORE_LIMIT int Number of edits textsw allows before vetoing destroy. Valid values 

are 0, meaning destroy will be vetoed if any edits have been done, and 
TEXTSW_INFINITY, meaning destroy will never be vetoed. Default: 
0 . 

TEXTSW_INSERT_FROM_FILE string inserts the contents of a file into 

a text subwindow at the current insertion point. 

TEXTSW I NSERT_MAKES_VI S IBLE Textsw_enum Controls whether insertion causes repositioning to make 

inserted text visible. Possible values are TEXTSW_ALWAYS, 
TEXTSW_NEVER and TEXTSW IF AUTO_SCROLL. 

Default: TEXTSW_IF_AUTO_SCROLL. 

TEXTSW INSERTION POINT Textsw_index Index of the current insertion point. Get, set. 

TEXTSW LEFT MARGIN int Number of pixels in the margin on left. Default: 4. Create, get. 

TEXTSW_LENGTH int Length of the textsw’s contents. Get only. 

TEXTSW L INE BREAK ACT ION Textsw_enum Determines how the textsw treats file lines too big 

to fit on one display line. Possible values are either 
TEXTSW_CLIP or TEXTSW_WRAP_AT_CHAR. 

Default: TEXTSW_WRAP_AT_CHAR. Create, set. 

TEXTSW LOWER_CONTEXT int Minimum # of lines to maintain between insertion point 

and the bottom of view. Used by auto scrolling when type-in 
would disappear off bottom of view. 

-1 means defeat auto scrolling. Default: 2. 
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Table 19-29 Text Subwindow Attributes — Continued 



Attribute 


Value Type 


Description 


TEXTSW_MEMORY__MAXIMUM 


int 


How much memory to use when not editing files. This attribute only 
takes effect at textsw window creation time or after the window has 
been reset via textsw_reset(). The lower bound of the attribute is 1000 
bytes which is silently enforced. Default: 20,000 bytes. (If a great 
deal of text will be inserted into the text subwindow, either by the pro- 
gram or the user, you may need to increase this.) 


TEXTSW_MENU 


Menu 


The text subwindow’s menu. Get, set. 


TEXTSW_MODIFIED 


boolean 


Whether or not the textsw has been modified. Get only. 


TEXTSW_MULTI_CLICK_SPACE 


int 


Max # of pixels that can be between successive mouse clicks 
and still have the clicks be considered a multi-click. Default: 3. 


TEXTSW_MULTI_CLICK_TIMEOUT 


int 


Max # of milliseconds that can be between successive 
mouse clicks and still have the clicks be considered 
a multi-click. Default: 390. 


TEXTSW_NOTIFY_PROC 


(procedure) 


Notify procedure. Form is: 
void 

notify proc (textsw, avlist) 
Textsw textsw 

Attr avlist avlist 
Default: NULL, meaning standard procedure. 


TEXTSW_READ ONLY 


boolean 


When TRUE, prevents editing of the displayed text. If another file 
is loaded in, READ ONLY is turned off again. Default: FALSE. 


TEXTSW_SCROLLBAR 


Scrollbar 


Scrollbar to use for text subwindow scrolling. 

NULL means no scrollbar. 

Default: A scrollbar with default attributes. 

Note: text subwindow has a scrollbar by default, so you would 
only use this to get no scrollbar, or to get the scrollbar handle. 


TEXTSW_STATUS 


Textsw_status * 


If set, specifies the address of a variable of type 
Textsw status into which a value is written that reflects 
what happened during the call to window_create(). 

(For possible values, see the Textsw _status Values table). 


TEXTSW_STORE_CHANGES_FI LE 


boolean 


If TRUE, Store changes the file being edited to that named 
as the target of the Store. If FALSE, Store does not affect 
which file is being edited. Default: TRUE. 


TEXTSW_STORE_SELF_IS_SAVE 


boolean 


Causes textsw to interpret a Store to the name of the current file 
as a Save. Default: FALSE. Create, get. 
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Table 19-29 


Text Subwindow Attributes — Continued 


Attribute 


Value Type 


Description 


TEXTSW_UPDATE_SCROLLBAR 


(no value) 


Causes text subwindow to update the bubble in the scrollbar. 
Set only — get returns NULL. 


TEXTSW_UPPER_CONTEXT 


int 


Min # of lines to maintain between the start of the selection and 
top of view. -1 means to defeat the normal actions. Default: 2. 






microsystems 



Revision A, of March 27, 1990 








Chapter 19 — SunView Interface Summary (Text sw_act ion Attributes) 341 



Table 19-30 Textsw action Attributes 



Attribute 


Value Type 


Description 


TEXTSW_ACTION_CAPS_LOCK 


boolean 


The user pressed the CAPS-lock function key to change the 
setting of the CAPS-lock (it is initially 0, meaning off). 


T EXTSW_AC T I ON_CHANGED_DI RECTORY 


char * 


The current working directory for the process has been 
changed to the directory named by the provided string value. 


TEXTSW_ACTION_EDITED_FILE 


char * 


The file named by the provided string value has been edited. 
Appears once per session of edits (see below). 


TEXTSW_ACTION_EDITED_MEMORY 


none 


monitors whether an empty text subwindow has been edited. 


TEXTSW_ACTION_FILE_IS_READONLY 


char * 


The file named by the provided string value does not have 
write permission. 


TEXTSW_ACTION_LOADED_FILE 


char * 


The text subwindow is being used to view the file named 
by the provided string value. 


TEXTSW_ACTION_TOOL_CLOSE 


(no value) 


The frame containing the text subwindow should become 
iconic. 


TEXTSW_ACTION_TOOL_DESTROY 


Event * 


The tool containing the text subwindow should exit, 
without checking for a veto from other subwindows. 
The value is the user action that caused the destroy. 


TEXTSW_ACT I0N_T00L_J2UI T 


Event * 


The tool containing the text subwindow should exit 
normally. The value is the user action that caused 
the exit. 


TEXTSW_ACTION_TOOL_MGR 


Event * 


The tool containing the text subwindow should do the 
window manager operation associated with the 
provided event value. 


TEXTSW ACT TON US I NG_MEMORY 


(no value) 


The text subwindow is being used to edit a string stored in 
primary memory, not a file. 
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Table 19-31 Textsw status Values 









Definition 



Description 



Textswmark 

textswaddmark ( textsw, position, flags) 
Textsw textsw; 

Textsw_index position; 
unsigned flags; 



int 

textswappendf ilename ( textsw, name ) 
Textsw textsw; 
char *name; 



Textsw_index 

textsw_delete( textsw, first, last_plus_one) 

Textsw textsw; 

Textsw_index first, last_plus_one ; 



Textsw_index 

textsw_edit( textsw, unit, count, direction) 
Textsw textsw; 

unsigned unit, count, direction; 



Textsw_index 

textswerase (textsw, first, last_plus_one ) 
Textsw textsw; 

Textsw_index first, last_plus_one ; 



void 

textswf ilelines visible (textsw, top, bottom) 
Textsw textsw; 
int *top, *bottom; 



int 

textsw_f ind_bytes ( textsw, first, last_plus_one, 
buf, buf_len, flags) 

Textsw textsw; 

Textsw_index *first, *last__plus_one; 

char *buf; 

unsigned buf_len, flags; 



A 



Adds a new mark at position. 

flags can be either TEXTSW_MARK_DEFAULTS or 

TEXTSW MARK MOVE AT INSERT. 



Returns 0 if textsw is editing a file, 

and if so appends the name of the file at the end of name. 



Returns 0 if the operation fails. 

Removes the span of characters beginning with first, 
and ending one before last_plus_one. 



Returns 0 if the operation fails. Erases a character, word or 
line, depending on whether un i t is SELN_LEVEL_FIRST, 
SELN_LEVEL_FIRST+1, or SELN_LEVEL_LINE. If 
direction is 0, characters after the insertion point are 
affected, otherwise characters before the insertion point are 
affected. The operation will be done count times. 



Returns 0 if the operation fails. 

Equivalent to textsw delete ( ),but does not 
affect the global shelf. 



Fills in top and bottom with the file line indices of 
the first and last file lines being displayed in textsw. 



Beginning at the position addressed by first, searches for the 
pattern specified by buf of length buf len. Searches 
forwards if flags is 0, else searches backwards. 

Returns -1 if no match, else matching span placed in 
indices addressed by first and last plus one. 
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Table 19-32 Text Subwindow Functions — Continued 



Definition 


Description 


Textsw index 

textsw findmark (textsw, mark) 
Textsw textsw; 

Textsw mark mark; 


Returns the current position of mark. If 

this operation fails, it will return TE XTS WIN FI NTT Y . 


Textsw 

textsw_f irst ( textsw) 
Textsw textsw; 


Returns the first view into textsw. 


Textsw_index 

textsw index_for file_line ( textsw , line) 
Textsw textsw; 
int line; 


Returns the character index for the first 
character in the line given by line. If this operation 
fails, it will return TEXTSW_CANNOT_SET. 


Textsw_index 

textsw insert (textsw, but, buf_len) 
Textsw textsw; 
char *buf; 

int buf len; 


Inserts characters in buf into textsw 
at the current insertion point. 

The number of characters actually inserted 
is returned — this will equal buf _1 en 
unless there was a memory allocation failure. 
If there was a failure, it will return 0. 


textsw match bytes ( textsw, first, last_plus one, 
start sym, start sym_len, 
end_sym, end sym len, field_flag) 
Textsw textsw; 

Textsw index *first, *last plus one; 
char *start sym, *end sym; 

int start_sym_len, end_sym_len; 

unsigned field flag; 


Searches for a block of text in the textsw ’s contents 
which starts with characters matching start sym and 
ends with characters matching end sym. 

This function places the starting index of the matching block in 
first and its ending index in last. 


Textsw 

textsw_next (textsw) 
Textsw textsw; 


Returns the next view in the set of views into textsw. 


void 

textsw_normalize_view( textsw, position) 
Textsw textsw; 

Textsw index position; 


Repositions the text so that the character 
at position is visible and at the top of the subwindow. 


void 

textsw possibly_normalize (textsw, position) 
Textsw textsw; 

Textsw index position; 


If the character at position is already visible, this function 
does nothing. If it is not visible, it repositions the text 
so that it is visible and at the top of the subwindow. 



n ii m 



microsystems 



Revision A, of March 27, 1990 










Chapter 19 — SunView Interface Summary ( Text Subwindow Functions ) 345 



Table 19-32 Text Subwindow Functions — Continued 



Definition 


Description 


void 

textsw remove mark (textsw, mark) 
Textsw textsw; 

Textsw_mark mark; 


Removes an existing mark from textsw. 


Textswindex 

textsw replace_bytes (textsw, first, 

last_plus_one , 
buf, buf_len) 
Textsw textsw; 

Textsw_index first; 
char *buf; 

unsigned buf_len; 


Replaces the character span from f ir st to 
last plus one by the characters in buf . 
last plus one. The return value is the net 
number of bytes inserted. The number is negative if the 
original string is longer than the one that replaces it. If 
this operation fails, it will return a value of 0. 


void 

textsw reset ( textsw, x, y) 
Textsw textsw; 
int x, y; 


Discards edits performed on the contents of textsw. 
If needed, a message box will be displayed at x, y. 


unsigned 

textsw save (textsw, x, y) 
Textsw textsw; 
int x, y; 


Saves any edits made to the file currently 
loaded into textsw.If needed, a message box 
will be displayed at x, y. 


int 

textsw screen line count ( texcsw) 
Textsw textsw; 


Returns the number of screen lines in textsw. 


void 

textsw scroll lines (textsw, count) 
Textsw textsw; 
int count; 


Moves the text up or down by count fines. If count 
is positive, then the text is scrolled up on the screen, 
(forward in the file); if negative, the text is scrolled down, 
(backward in the file). 


void 

textsw set_selection (textsw, first, last_plus_one, 

type) 

Textsw textsw; 

Textsw index first, last_plus_one ; 
unsigned type; 


Sets the selection to begin at f irst and include all 
characters up to last plus one. 
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Table 1 9-32 Text Submndovc Functions — Con tinued 





Definition 


Description 


unsigned 
textsw store 


file(textsw, filename, x, y) 


Stores the contents of textsw 


Textsw 


textsw; 


to the file named by f i lename. If needed, a 


char 


*f ilename; 


message box will be displayed at x, y. 


int 


x, y; 
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Table 19-33 TTY Subwindow Attributes 



Attribute 


Type 


Description 


TTY_ARGV 


char ** 


Argument vector: name of the program 
running in the tty subwindow, followed by 
arguments for that program. Setting 
TTY_ARGV to 

TT Y_ ARG V_DO_N OT_FORK prevents 
the forking of a child process in the tty sw 


TTY_CONSOLE 


boolean 


If TRUE, tty subwindow is console. Set 
only. Default: FALSE. 


TTY_PID 


int 


Process id of child process running in tty sw 


TTY_PAGE_MODE 


boolean 


If TRUE, output will stop after each page. 
Default: FALSE. 


TTY_QUIT_ON_CHILD_DEATH 


boolean 


If TRUE, window done ( ) is called on 
the subwindow when its child terminates. 
Set only. Default: FALSE. 


TTY_TTY_FD 


int 


File descriptor of tty sw 


Table 19-34 


TTY Subwindow Functions 





Definition 




Description 


int 

ttysw_input ( tty , buf. 
Tty tty; 

char *buf ; 
int len; 


len ) 


Appends len number of characters from buf 
onto tty’s input queue. It returns the number 
of characters accepted. 


int 

ttysw_output ( tty , buf, 
Tty tty; 

char *buf ; 


. len ) 
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Table 19-34 TTY Subwindow Functions — Continued 

Definition Description 

int len; 



Appends len number of characters from buf 
onto tty’s output queue, i.e. they are sent 
through the terminal emulator to the TTY. It 
returns the number of characters accepted. 
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Table 19-35 TTY Subwindow Special Escape Sequences 



Escape Sequence 104 


Description 


\E [It 


open frame. 


\E[2t 


close frame. 


\E[3t 


move frame with interactive feedback. 


\E [ 3 ; TOP ; LEFTt 


move frame to location specified by (TOP,LEFT). 


\E [ 4 1 


resize frame with interactive feedback. 


\E [ 4 ; WIDTH ; HEIGHTt 


resize frame to WIDTH and HEIGHT. 


\E[5t 


expose. 


\E [ 6 1 


hide. 


\E[7t 


redisplay. 


\E [ 8 ; ROWS ; COLSt 


resize frame so its width and height are ROWS and COLS. 


\E [ lit 


report if frame is open or closed by sending \ [ It or \ [ 2 1, respectively. 


\E[13t 


report frame’s position by sending the \E [ 3 ; TOP ; LEFT t sequence. 


\E[14t 


report frame’s size in pixels by sending the \E [ 3 ; WIDTH ; HEIGHT t sequence. 


\E[18t 


report frame’s size in characters by sending the \E [ 8 ; ROWS; COLS t sequence. 


\E [ 2 Ot 


report the frame icon’s label by sending the \E [ Llabet\E\ sequence. 


\E[21t 


report frame’s label by sending the \E] llabel\E\ sequence. 


\E ] ltex*\E\ 


set frame’s label to text. 


\E)lJUe\E\ 


set frame’s icon to the icon contained in file. 


\E ] Llabel\E\ 


set icon’s label to label. 


\E [>OPTl ; . . . OPTnh 


turn requested options on. The only currently defined option is 1, for TTY PAGE MODE. 


\E [>OPTl ; . .OPTrik 


turn requested options off. 
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Table 19-35 


TTY Subwindow Special Escape Sequences — Continued 


Escape Sequence 104 


Description 


\E [>OPTl ; . . .OPTnl 


report current option settings by sending \E [ >OPTxl or \E>OP7'h for each option jc. 



104 In this table *\E” denotes the <ESC> character, as it does in termcap. 
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Table 19-36 Window Attributes 



Attribute 


Value Type 


Description 


WIN_ALARM 


Win_alarm 


Ring alarm with characteristics specified in structure 


WIN BELOW 


Window 


Causes the window to be laid out below window given as the value. 


WI N_B0T TOM MARG I N 


int 


Margin at bottom of window. 


WIN_CLIENT_DATA 


caddr_t 


Client’s private data — for your use. 


WI N_C0LUMNS 


int 


Window’s width (including left and right margins) in columns. 


WIN_COLUMN_GAP 


int 


Gap between columns in the window. 


WIN_COLUMN_WIDTH 


int 


Width of a column in the window. 


WIN__CONSUME_KBD_EVENT 


short 


Window will receive this event. 


WIN_CONSUME_KBD_EVENTS 


list of short 


Null terminated list of events window will receive. Create, set. 


WIN_CONSUME_PICK_EVENT 


short 


Window will receive this pick event. 


WIN_CONSUME_PICK_EVENTS 


list of short 


Null terminated list of pick events window will receive. Create, set. 


WIN CURSOR 


Cursor 


The window’s cursor. Note: the pointer returned by 
window get ( ) points to per-process static storage. 


WIN_DEVICE_NAME 


char * 


UNIX device name associated with window, consisting of a string and 
numeric part, e.g. winlO. Get only. 


WI NDEV I CE_NUMBER 


int 


Numeric component of device name. Get only. 


WIN_ERROR_MSG 


char * 


Error message to print before exit(l). Create only. 


WIN _EVENT_PROC 


(procedure) 


Client’s callback procedure which receives input events: 

Notif y value 

event proc (window, event, arg) 

Window window; 

Event * event; 
caddr t arg; 


WIN_EVENT_STATE 


short 


Gets the state of the specified event code. For buttons and keys, 
zero means “up,” non-zero means “down.” Get only. 


WIN_FD 


int 


The UNIX file descriptor for the window. Get only. 


WIN_FIT_HEIGHT 


int 


Causes window to fit its contents in the height dimension. 
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Table 19-36 Window Attributes — Continued 



Attribute 


Value Type 


Description 






leaving a margin specified by the value given. 


WIN_FIT_WIDTH 


int 


Causes window to fit its contents in the width dimension, 
leaving a margin specified by the value given. 


WIN_FONT 


Pixfont * 


The window’s font. Notes for the current release: 

tty subwindows don’t use WIN FONT. Frames don’t use WIN FONT 

to render their labels; however, they do use WI N FONT 

in calculating WIN_COLUMNS and WIN ROWS. Setting WIN_FONT 

does not cause the default system font to be set. 


WI N_GRAB_ALL_I NPUT 


boolean 


Window will get all events regardless of location, (set only) 


WIN_HEIGHT 


int 


Window’s height in pixels. Value of WIN EXTEND TO EDGE 
causes subwindow to extend to bottom edge of frame. 

Default: WIN_EXTEND_TO_EDGE. 


WI N_HOR I ZONT AL_SCROLLBAR 


Scrollbar 


Horizontal scrollbar. 


WI N_IGNORE_KBD_EVENT 


short 


Window will not receive this event. 


WIN_IGNORE_KBD_EVENTS 


list of short 


Null terminated list of events window will not receive. Create, set. 


WIN_IGNORE_PICK_EVENT 


short 


Window will not receive this pick event. 


WIN_IGNORE_PICK_EVENTS 


list of short 


Null terminated list of pick events window will not receive. Create, set. 


WIN INPUT_DESIGNEE 


int 


Window which gets events this window doesn’t consume. (Note that 
the value must be the WIN DEVICE NUMBER of the designee). 


WINJKBD_FOCUS 


boolean 


Whether or not the window has the keyboard focus. 


WI N_KBDJNPUT MASK 


Inputmask * 


Window’s keyboard inputmask. Note: the pointer returned by 
window get ( ) points to per-process static storage. 


WINLEFTMARGIN 


int 


Margin at left of window. 


WIN_MENU 


Menu 


Window’s menu. Note: In the current release this doesn’t work for 
panels or tty subwindows. 


W I N_MOU S E_X Y 


int, int 


Mouse’s position within the window. Set only. 


WIN_NAME 


char * 


Name of window (currently unused by SunView). 


WIN__OWNER 


Window 


Owner of window. Get only. 
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Table 19-36 Window Attributes — Continued 



Attribute 


Value Type 


Description 


WI N_PERCENT_HEIGHT 


int 


Sets a subwindow’s height as a percentage of the frame’s height. 


WIN_PERCENT_WIDTH 


int 


Sets a subwindow’s width as a percentage of the frame’s width. 


WIN_PICK_INPUT_MASK 


Inputmask * 


Window’s pick inputmask. Note: the pointer returned by 
window get ( ) points to per-process static storage. 


WIN^PIXWIN 


Pixwin * 


The window’s pixwin. Get only. 


WI N_RECT 


Rect * 


Rect of the window. For frames, same as FRAME OPEN RECT. 
Note: the pointer returned by window get ( ) for this attribute 
points to per-process static storage. 


WIN_RIGHT MARGIN 


int 


Margin at right of window. 


WI N_RIGHT_OF 


Window 


Causes the window to be laid out just to the 
right of the window given as the value. 


WI N_ROW_G AP 


int 


Gap between rows in the window. 


WI N_ROW_HEIGHT 


int 


Height of a row in the window. 


WINROWS 


int 


Window’s height (including top and bottom margins) in rows. 


WIN_SCREEN__RECT 


Rect * 


Rect of the screen containing the window. Get only. 

Note: the pointer returned by window get ( ) for this attribute 
points to per-process static storage. 


WIN SHOW 


boolean 


Causes the window to be displayed or undisplayed. 


WIN_TOP_MARGIN 


int 


Margin at top of window. 


WIN^TYPE 


Window_type 


Type of window. One of FRAME_TYPE, PANEL_TYPE, 
CANVASTYPE, TEXTSW TYPE or TTY TYPE. Get only. 


WIN_VERT I CAL SCROLLBAR 


Scrollbar 


Vertical scrollbar. 


WIN_WIDTH 


int 


Window’s width in pixels. Value of WIN EXTEND TO EDGE 
causes subwindow to extend to right edge of frame. 

Default: WIN_EXTEND_TO__EDGE. 


WIN_X 


int 


x position of window, relative to owner. 


WINY 


int 


y position of window, relative to owner. 
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Table 19-37 Frame Attributes 



Attribute 


Value Type 


Description 


FRAME_ARGS 


int, char ** 


Interpret command line arguments. Strips -W command-line frame 
arguments out of argv. Create only. 


FRAME_ARGC_PTR_ARGV 


int *, char ** 


Interpret command line args. Strips -W command-line frame argu- 
ments out of argv, and decrements argc accordingly. Create only. 


FRAME_BACKGROUND_COLOR 


struct singlecolor * 


Background color. 


FRAME_CL0SED 


boolean 


Whether frame is currently closed. 


FRAME_CLOSED_RECT 


Rect * 


Frame’s rect when closed. 


FRAME_CMDLINE_HELP_PROC 


(procedure) 


Called when user types the command-line argument -WH. Default: 
frame cmdline help (program_name) 
char *program name; 


FRAME_CURRENT_RECT 


Rect * 


Returns either FRAME_OPEN_RECT or FRAME_CLOSED_RECT, 
depending on the value of FRAME CLOSED. 

Note: in the current release, there is a bug in the behavior 
of FRAME_CURRENT_RECT for subframes. It is set relative 
to the owner frame, but it is retrieved relative to the screen. 


FRAME_DEFAULT_DONE_PROC 


(procedure) 


Default value of FRAME_DONE_PROC. Get only. 

The default procedure is to set the subframe to WI N SHOW , FALSE. 


FRAME_DONE_PROC 


(procedure) 


Client’s proc called when user chooses ‘Done’ from subframe’s menu: 

done proc (frame) 

Frame frame; 


FRAME_EMBOLDEN_LABEL 


boolean 


If TRUE, frame’s label is rendered in bold. 


FRAME_FOREGROUND_COLOR 


struct singlecolor * 


Foreground color. 


FRAME ICON 


Icon 


The frame’s icon. 


FRAME_I NHERI T_COLORS 


boolean 


If TRUE, colormap of frame is inherited by subwindows. 


FRAME_LABEL 


char * 


The frame’s label. 


FRAME_NO_CONFI RM 


boolean 


Set to TRUE before destroying a frame 
to defeat confirmation. Set only. 


FRAME_NTH_SUBFRAME 


int 


Returns frame’s nth (from 0) subframe. Get only. 
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Table 1 9-37 Frame A ttributes — Continued 



Attribute 


Value Type 


Description 


FRAME_NTH_SUBWINDOW 


int 


Returns frame’s nth (from 0) subwindow. Get only. 


FRAME_NTH_WI NDOW 


int 


Returns frame’s nth (from 0) window, regardless of whether 
the window is a frame or a sub window. Get only. 


FRAME_SHOW_LABEL 


boolean 


Whether the label is shown. Default: 

TRUE for base frames, FALSE for subframes. 


FRAME_OPEN_RECT 


Rect * 


Frame’s rect when open. 


FRAME_PROPS_ACTION_PROC 


(procedure) 


Callback to handle frame’s property sheet: 
void procedure () 


FRAME_PROPS_ACTIVE 


boolean 


Set TRUE to enable property sheet procedure 


FRAME_SHOW_SHADOW 


boolean 


Whether drop shadow behind frame. 

FALSE for base frames, TRUE for subframes, 
shadow uses 1 extra file descriptor 


FRAME_SUBWINDOWS_AD JUST ABLE 


boolean 


User can move subwindow boundaries. Default: TRUE. 
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Table 19-38 Window Functions and Macros 



Definition 


Description 


void 

window bell (win) 
Window win; 


Queries the user defaults database 
to see if the user wants the bell to be 
sounded, the window to be flashed, or both. 


Window 

window create (owner , type, attributes) 
Window owner; 

<window type> type; 

<attribute-list> attributes; 


Creates a window and returns its handle, 
type is one of FRAME, PANEL 
TEXTSW, TTY, or CANVAS. 


void 

window default event_proc (window, event, arg) 
Window window; 

Event *event; 

caddr t arg; 


Calls the default event procedure. 

The arguments passed in are the window (canvas or panel), 
the event, and an optional argument pertaining to the event. 


window_destroy (win) 
Window win; 


Destroys win, and any subwindows or 
subframes owned by win. 


window done(win) 
Window win; 


Destroys the entire hierarchy to which win belongs. 


window fit(win) 
Window win; 


Causes win to fit its contents 

in both dimensions. A macro, defined as: 

window set(win, WIN_FIT, 0, 0). 


window fit height(win) 
Window win; 


Causes win to fit its contents 

in the vertical dimension. A macro, defined as: 

window set (win, WIN_FIT_HEIGHT , 0, 0). 


window_f it_width(win) 
Window win; 


Causes win to fit its contents 

in the horizontal dimension. A macro, defined as: 

window_set (win, WIN FITWIDTH, 0, 0). 


caddr t 

window get(win, attribute) 
Window win; 

Window attribute attribute; 


Retrieves the value of an attribute for win. 
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Table 19-38 Window' Functions and Macros — Continued 



Definition 


Description 


caddrt 

window loop (subframe) 
Frame subframe; 


Causes subframe to be displayed, and receive all 
input. The call will not return until window return ( ) 
is called from one of the application’s notify procs. 


void 

window_main_loop(base_f rame) 
Frame base_frame; 


Displays basef rame on the screen and begins the 
processing of events by passing control to the Notifier. 


int 

window_read_event (window, event) 
Window window; 

Event * event; 


Reads the next input event for window. 

In case of error, sets the global variable err no 
and returns -1. 


void 

window_refuse_kbd_focus (window) 
Window window; 


When your event handler receives a KBD_REQUEST 
event, call this function if you do not want your 
window to become the keyboard focus. 


void 

window_release_event_lock (window) 
Window window; 


Releases the event lock, allowing other processes to receive input. 


void 

window return (value) 
caddr_t value; 


Usually called from one of the application’s panel item 
notify procs. Causes window_loop ( ) to return. 


window set (win, attributes) 
Window win; 

<attribute-list> attributes; 


Sets the value of one or more of win’s attributes, 
attributes is a null-terminated attribute list. 
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Table 1 9-39 Command Line Frame Arguments 



Flag 


Long F/ag 


Arguments 


Corresponding Attributes 


-Wb 


-background_color 


red green blue 


FRAME_BACKGROUND_COLOR 


-Wh 


-height 


lines 


WIN_R0WS 


-WH 


-help 


— 


(Causes FRAME_CMDLINE_HELP_PROC to be called.) 


-Wf 


- f oreground_color 


red green blue 


FRAME_FOREGROUND_COLOR 


-Wg 


- set_de£aul t_color 


— 


FRAME_I NHERI T_C0L0RS , TRUE 


-Wi 


-iconic 


— 


FRAME_CLOSED , TRUE 


-WI 


- icon_image 


filename 


ICON_IMAGE of frame’s icon 106 


-WI 


-label 


label 


FRAME_LABEL 


-WL 


-icon_label 


label 


ICON_LABEL of frame’s icon 


-Wn 


-no_name_s tripe 


— 


FRAME_SHOW_LABEL , FALSE 


-Wp 


-position 


xy 


WIN_X, WIN_Y 


-WP 


-icon_position 


xy 


FRAME_CLOSED_RECT 


-Ws 


-size 


xy 


WIN_WIDTH, WIN_HEIGHT 


-Wt 


-font 


pathname 

Use full pathname for reliability. 


(Sets system default font) 


-WT 


-icon_font 


pathname 

Use full pathname for reliability. 


IC0N_F0NT of frame’s icon 


-Ww 


-width 


columns 


WIN_COLUMNS 



106 The -WI option will not work if the application’s code does not already specify its icon. 
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Source Available 



A.l. filer 




Example Programs 



If the appropriate optional software category has been installed or mounted on 
your system, the source code for some of these examples programs is available 
on-line in /usr/share/src/sun/suntool/examples. In addition, the 
directory above this (/usr/share/src/sun/suntool) contains the source 
for many of the SunView 1 programs in the SunOS, such as textedit, 
perfmeter, and iconedit. 



This program is discussed in Chapter 4, Using Windows. It displays a listing in a 
tty subwindow, which the user manipulates through panel items. 

If the user presses the [ Props 1 key in the panel, or chooses ‘Props’ from the frame 
menu, or pushes the Set Is flags button, a pop-up subframe appears, filer uses the 
Selection Service to determine what file name the user has selected, and creates a 
pop-up text subwindow where that file is displayed. 

filer uses the alerts package to ask the user for confirmation and put up messages. 
It also includes old code which mimics alerts by using window loop ( ) to put 
up a subframe, but programs written for SunOS Release 4.0 and beyond in gen- 
eral will have no need for this. 



#sun 

microsystems 



359 



Revision A, of March 27, 1990 




360 SunView Programmer’s Guide 



/***************************************************************************** ^/ 

/* V 

/* filer. c */ 

/* */ 

/*****************************************************************************^ 
/*****************************************************************************^ 
/* V 

/* This program displays a control panel and a tty subwindow. Given that the*/ 

/* user specifies the directory and file, and then pushes the List button, */ 

/* this will cause the Is command to be sent to the tty subwindow. Pop-ups */ 

/* are implemented as subframes containing subwindows in this application. */ 

/* The three buttons Set Is flags, Edit, and Delete allow the user to set */ 

/* options for the Is command, browse and edit files, and confirm or to */ 

/* cancel. The user of this application has the ability to close, move, */ 

/* resize, hide, redisplay, or quit the window. */ 

/* V 



/ 



***************************** 



#include <suntool/sunview.h> 

#include <suntool/panel . h> 

^include <suntool/tty . h> 

#include <suntool/textsw. h> 

#include <suntool/seln . h> 

#include <suntool/alert . h> 

#include <sys/stat.h> /* stat call needed to verify existence of files */ 

/* these objects are global so their attributes can be modified or retrieved */ 
base_frame, edit_frame, ls_f lags_frame; 
panel, ls_f lags_panel ; 
ttysw; 
editsw; 

dir_item, fname_item, f iling_mode_item, done_item; 
quit_conf irmed_f rom_panel ; 

MAX_FILENAME_LEN 256 

MAX PATH LEN 1024 



Frame 

Panel 

Tty 

Textsw 

Panel_item 

int 

#def ine 
#def ine 
char *getwd(); 
main(argc, argv) 
int argc; 
char **argv; 



{ 



static Notify_value f iler_destroy_f unc { ) ; 
void lsf lagsproc ( ) ; 

base_frame = window_create (NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "filer", 

FRAME_PROPS_ACTION_PROC , ls_f lags_proc , 
FRAME_PROPS_ACTIVE, TRUE, 

FRAME_NO_CONFIRM, TRUE, 

0 ) ; 

(void) notify_interpose_destroy_f unc (base_frame, f iler_destroy_func) ; 

create_panel_subwindow( ) ; 

create_tty_subwindow( ) ; 

create_edit_popup ( ) ; 

create_ls_f lagspopup ( ) ; 

quit_conf irmed_from_panel = 0; 

window_main loop (base_frame) ; 

exit ( 0 ) ; 

} 

create_tty_subwindow( ) 
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ttysw - window_c reate (base_f rame, TTY, 0); 

} 

create_edit_popup ( ) 

{ 

edit_frame = window_create (base_frame, FRAME, 

FRAME_SHOW_LABEL, TRUE, 

0); 

editsw - window_create (edit_frame, TEXTSW, 0); 

} 

create_panel_subwindow ( ) 

{ 

void ls_proc () , ls_f lags_proc () , quit_proc () , edit_proc () , 
edit_sel_proc () , deljproc () ; 

char current_dir [MAX_PATH_LEN] ; 

panel = window_create (base_f rame, PANEL, 0); 

(void) panel_create_item (panel, PANEL_BUTTON, 

PANEL_LABEL_X , ATTR_C0L ( 0 ) , 

PANE L_LABE L_Y , ATTR_R0W ( 0 ) , 

PANEL_LABEL_IMAGE , panel_button_image (panel, "List Directory", 0, 0) , 

P ANEL_N0T I F Y_PROC , 1 s_p r o c , 

0) ; 

(void) pane l_create_item (panel, PANEL_BUTTON , 

PANEL_LABEL_IMAGE , panel_button_image (panel, "Set Is flags", 0, 0), 

PANEL_NOTIFY_PROC, ls_f lags_j>roc, 

0); 

(void) panel_create_item (panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, "Edit", 0, 0), 

PANEL_NOTIFY_PROC, edit_proc, 

0); 

(void) panel_create_item (panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, "Delete", 0, 0), 

PANEL_NOTIFY_PROC, del_proc, 

0); 

(void) panel_create_item (panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, "Quit", 0, 0), 

PANEL_NOTIFY_PROC, quit_proc, 

0) ; 

f iling_mode_item = panel_create_item (panel, PANEL_CYCLE, 

PANE L_LABE L_X , ATTR_C0L ( 0 ) , 

PANE L_LABE L_Y , ATTR_R0W ( 1 ) , 

P ANEL_LABEL_STR I NG , "Filing Mode:", 

PANEL_CHOICE_STRINGS, "Use V'File: \" item", 

"Use Current Selection", 0, 

0); 



(void) panel_create_item (panel, P ANEL_MESSAGE , 
PANEL_LABEL_X , ATTR_C0L ( 0 ) , 

PANE L_LABE L_Y , ATTR_R0W ( 2 ) , 

0 ) ; 

dir_item = panel_create_item (panel, PANEL_TEXT, 
PANEL_LABEL_X , ATTR_C0L ( 0 ) , 

PANE L_LABE L_Y , ATTR_R0W ( 3 ) , 

PANEL_VALUE_D I SPLAY_LENGTH , 60, 

PANEL_VALUE, getwd (current_dir) , 

PANEL_LABEL_STRING, "Directory: ", 
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r~ 




0); 












fname_item = panel_create item (panel, PANEL TEXT, 










PANEL LABEL_X, 


ATTR_C0L ( 0 ) , 










PANEL_LABEL_Y, 


ATTR_ROW(4 ) , 










PANEL LABEL DISPLAY LENGTH, 


60, 










PANEL J^BELJSTRING, 
n \ • 


"File: ", 










u ) > 

window fit_height (panel) ; 










i 


windowset (panel , PANEL_CARET_ITEM, fnameitem, 0); 








j 

create_ls_flags_popup( ) 
r 










l 


void done_proc(); 












ls_f lags_f rame = window_create (base frame, FRAME, 0); 










ls_f lags_panel = windowcreate ( Is 


_f lags_frame, PANEL, 0); 










panel_create_item ( ls_f lags panel , 


PANEL_MESSAGE , 










PANEL_ITEM_X, 


ATTR_COL ( 14 ) , 










PANEL_ITEM_Y, 


ATTR_ROW(0) , 










PANEL_LABEL_STRING , 


"Options for Is command". 










PANEL CLIENT DATA, 


If If 

f 










0); 












panel_create_item ( ls_f lags_panel , 


PANEL_CYCLE, 










PANEL_I TEM_X , 


ATTR_COL ( 0 ) , 










PANEL_ITEM_Y, 


ATTR_ROW ( 1 ) , 










PANEL_DISPLAY_LEVEL, 


PANEL_CURRENT, 










PANEL_LABEL_STRING , 


"Format : 


If 

/ 








PANEL_CHOICE_STRINGS , 


"Short", "Long", 0, 










PANEL_CLIENT_DATA , 


" 1 ", 










0); 












panel_create_item ( ls_f lags panel , 


PANEL_CYCLE, 










PANEL_I TEM_X , 


ATTR_COL ( 0 ) , 










PANEL_ITEM_Y, 


ATTR_ROW ( 2 ) , 










PANEL DISPLAY LEVEL, 


PANEL CURRENT, 










PANEL LABEL STRING, 


"Sort Order: 


II 

f 








PANEL_CHOICE_STRINGS , 


"Descending", "Ascending", 0, 










PANEL_CLIENT_DATA, 


If r II 
i / 










u ; / 

panel create_item ( ls__f lags panel, 


PANEL_CYCLE , 










PANEL ITEM_X, 


ATTR COL ( 0 ) , 










PANEL__ITEM_Y , 


ATTR_ROW ( 3 ) , 










PANEL DISPLAY LEVEL, 


PANEL CURRENT, 










PANEL_LABEL STRING, 


"Sort criterion: 


II 

/ 








PANEL_CHOICE STRINGS, 


"Name", "Modification Time", 












"Access Time", 0, 










PANEL CLIENT DATA, 


" tu", 










0); 












panel_create_item ( lsf lags panel , 


PANEL_CYCLE, 










PANEL_I TEM_X , 


ATTR_COL ( 0 ) , 










PANEL_I TEM_Y , 


ATTR_ROW(4 ) , 










PANEL DISPLAY LEVEL, 


PANEL CURRENT, 










PANEL LABEL STRING, 


"For directories, list: 


II 

/ 








PANEL_CHOICE_STRINGS, 


"Contents", "Name Only", 0, 










PANEL CLIENT DATA, 


" d ", 










0); 












panel_create_item ( ls_f lags panel , 


PANEL_CYCLE, 










PANEL_ITEM_X, 


ATTR_COL ( 0 ) , 










PANEL_ITEM_Y, 


ATTR_ROW ( 5 ) , 










PANEL_DISPLAY_LEVEL, 


PANEL_CURRENT , 

















J 
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"Recursively list subdirectories? 
"No", "Yes", 0, 

" R ", 



PANEL_LABEL_STRING , 

PANEL_CHOICE_STRINGS , 

PANEL_CLIENT_DATA, 

0 ); 

panel_create_item ( ls_f lags_panel , 

PANEL_I TEM_X , 

PANEL_ITEM_Y, 

PANEL_DISPLAY_LEVEL, 

PANEL_L ABEL_ST R I NG , 

PANEL_CHOICE_STRINGS , 

PANEL_CLIENT_DATA , 

0 ); 

panel_create_item ( ls_f lags_panel , 

PANEL_ITEM_X, 

PANEL__ITEM_Y, 

PANEL_DI SPLAY_LEVEL , 

PANEL_LABEL_STRING, 

PANEL_CHOICE_STRINGS , 

PANEL_CLIENT_DATA , 

0 ); 

done_item = panel_create_item ( ls_f lagspanel , PANEL_BUTTON, 



PANEL_CYCLE , 

ATTR_COL ( 0 ) , 

ATTR_ROW ( 6 ) , 
PANEL_CURRENT , 

"List ' . ' files? 

"No", "Yes", 0, 

" a ", 

PANEL_CYCLE, 

ATTR_COL(0) , 

ATTR_ROW ( 6 ) , 
PANEL_CURRENT, 

"Indicate type of file? 
"No", "Yes", 0, 

" F ", 



ATTR_COL ( 0 ) , 

ATTR_ROW ( 7 ) , 

panel_button_image (panel , "Done", 0, 0), 
done_proc, 



flags [20 ] ; 

*ptr ; 
flag; 

first_flag = TRUE, 
item ; 

*client_data ; 
index; 



PANEL_ITEM_X, 

PANEL_ITEM_Y, 

PANEL_LABEL_IMAGE , 

PANEL_NOT IFY_PROC , 

0 ); 

window_f it ( ls_f lags_panel ) ; /* fit panel around its items */ 
window_f it ( ls_f lags_f rame) ; /* fit frame around its panel */ 

1 

char * 

compose_ls_options ( ) 

{ 

static char 
char 
char 
int 

Panel_item 
char 
int 

ptr = flags; 

panel_each_item ( ls_f lags_panel , item) 
if (item != done_item) { 

client_data = panel_get ( item, PANEL_CLIENT_DATA, 0); 
index = ( int )panel_get_value( item) ; 
flag = client_data [ index] ; 
if ( flag ! = ' ' ) [ 

if (first_flag) { 

*ptr++ = 
first_flag = FALSE; 

} 

*ptr++ = flag; 

} 

1 

panel_end_each 
* P tr = ' '; 
return flags; 
a 

J 

void 
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lsproc ( ) 

{ 

static char previous_dir [ MAX_PATH_LEN ] ; 
char *current_dir ; 

char cmdstring [ 100 ] ; /* dir_item's value can be 80, plus flags */ 

current_dir = (char * )panel_get_value (dir_item) ; 
if (strcmp (current_dir, previous_dir ) ) { 

chdir ( (char * )panel_get_value (dir_item) ) ; 
strcpy (previousdir, current_dir) ; 

} 

sprintf (cmdstring, "/usr/bin/ls %s %s/%s 0, 
compose_ls_options ( ) , 
current_dir , 

panel_get_value(fname_item) ) ; 
ttysw_input ( ttysw, cmdstring, strlen(cmdstring) ) ; 

} 

void 

ls_f lags_proc ( ) 

i 

window_set (ls_flags_frame, WIN_SHOW, TRUE, 0); 

] 

void 

done_proc ( ) 

{ 

window_set(ls_f lags_frame, WIN_SHOW, FALSE, 0); 

} 

/* return a pointer to the current selection */ 
char * 

get_selection ( ) 

f 

static char f ilename[MAX_FILENAME_LEN] ; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire ( SELN_PRIMARY) ; 

buffer = seln_ask ( &holder , SELN_REQ_CONTENTS_ASC I I , 0, 0); 
strncpy ( 

filename, buffer->data + sizeof (Seln_attribute ) , MAX_FILENAME_LEN) ; 
return (filename) ; 

1 

/* return 1 if file exists, else print error message and return 0 */ 
stat_f ile (filename) 
char *filename; 

{ 

static char previous_dir [MAX_PATH_LEN] ; 
char *current_dir; 
char this_f ile [MAX_PATH_LENj ; 
struct stat statbuf; 

current_dir = (char * ) panel_get_value(dir_item) ; 
if ( strcmp (currentdir , previous_dir ) ) { 

chdir ( ( char * )panel_get_value (dir_item) ) ; 
strcpy (previous_dir, current_dir) ; 

} 

sprintf (this_f ile, "%s/%s", current_dir, filename); 
if (stat ( this_f ile, Sstatbuf) < 0) { 

char buf [MAX_FILENAME_LEN+11 ] ; /* big enough for message */ 

sprintf (buf, "%s not found.", this_file); 
msg(buf , 1) ; 
return 0; 

v ; ) 
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msg( "Please select a file to delete.", 1); 
return ; 

} 

] else { 

if ( Jstrlen (filename = (char * ) panel_get_value ( f name_item) ) ) { 
msg( "Please enter a file name to delete.", 1); 
return ; 

} 

) 

/* return if file not found */ 
if ( !stat_file(filename) ) 
return ; 

/* user must confirm the delete */ 
result = alertprompt (base_f rame, &event, 

ALERT_MESSAGE_STRINGS, 

"Ok to delete file:", 
filename, 

0, 

ALERT_BUTTON_YES, "Confirm, delete file", 

ALERT_BUTTON NO , " Cancel " , 

Bi- 
switch (result) { 
case ALERTYES: 

unlink ( filename) ; 

sprintf(buf, "%s deleted.", filename); 

msg(buf , 0) ; 

break; 

case ALERTNO: 
break; 

case ALERT_FAILED : /* not likely to happen unless out of memory */ 
sprintf(buf, "Ok to delete file %s?", filename); 
result = conf irm_yes (buf ) ; 
if (result) { 

unlink (filename) ; 

sprintf(buf, "%s deleted.", filename); 
msg(buf, 1); 

} 

break ; 

] 

} 

int 

conf irm_quit ( ) 

{ 

int result; 

Event event; /* unused */ 

char *msg = "Are you sure you want to Quit?"; 
result = alert_prompt (base_frame, &event, 

ALERT_MESSAGE_STRINGS , 

"Are you sure you want to Quit?", 

0 , 

ALERT_BUTTON_YES , "Confirm", 

ALERT_BUTTON_NO, "Cancel", 

0) ; 

switch (result) { 
case ALERT_YES : 
break ; 

case ALERT_N0: 
return 0 ; 

v J 
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case ALERT_FAILED: /* not likely to happen unless out of memory */ 
result — conf irm_yes (msg) ; 
if (! result) { 
return 0; 

} 

break; 

} 

return 1 ; 

} 

static Notify__value 
f iler_destroy_func (client, status) 

Notify_client client; 

Destroy_status status; 

{ 

if (status — DE STROY_CHECK ING ) { 

if (quit_conf irmed_f rom_panel) { 

return (notify_next_destroy_func (client, status) ) ; 

} else if (confirm_quit () — 0) { 

(void) notify__veto_destroy ( (Notify_client) (LINT_CAST (client) ) ) ; 
return (N0TIFY_D0NE) ; 

} 

} 

return (notify_next_destroy_func (client, status) ) ; 

} 

void 

quit_proc () 

( 

if (confirm_quit () ) { 

quit_confirmed_from_panel — 1; 
window_destroy (base_frame) ; 



msg (msg, beep) 
char *msg; 
int beep; 

{ 

char buf[300]; 

int result; 

Event event; /* unused */ 

char *contine_msg = "Press \"Continue \" to proceed."; 



result = alert_prompt (base_f rame, Sevent, 

ALERT_MESSAGE_STRINGS , 
msg, 

contine_msg, 

0 , 

ALERT_NO_BEEP ING, (beep) ? 0:1, 

ALERT_BUTT 0N_YE S , " Cont inue " , 

ALERT_TRIGGER, ACTI0N_ST0P, /* allow either YES or NO answer */ 

0 ); 

switch (result) { 
case ALERT_YES: 

case ALERT_TRIGGERED : /* result of ACTI0N_ST0P trigger */ 
break; 

case ALERT_FAILED : /* not likely to happen unless out of memory */ 
sprintf(buf, "%s Press V'Continue V to proceed.", msg); 
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result 

break; 



confirm ok(buf); 



/* confirmer routines to be used if alert fails for any reason */ 

static Frame init_conf irmer () ; 

static int confirm(); 

static void yes_no_ok () ; 

int 

confirm_yes (message) 

char *message; 

{ 

return confirm (message, FALSE); 

} 

int 

confirm_ok (message) 

char *message; 

{ 

return confirm (message, TRUE); 

} 

static int 

confirm (message, ok_only) 
char *message; 

int ok_only; 

{ 

Frame confirmer; 

int answer; 

/* create the confirmer */ 

confirmer = init_conf irmer (message, ok_only) ; 

/* make the user answer */ 

answer = (int) window_loop (confirmer) ; 

/* destroy the confirmer */ 

window_set (confirmer, FRAME_NO_CONFIRM, TRUE, 0); 
window_destroy (confirmer) ; 
return answer; 

} 

static Frame 

init_conf irmer (message, ok_only) 
char *message; 

int ok_only; 



Frame confirmer; 

Panel panel ; 

Panel_item message_item; 

int left, top, width, height; 

Rect *r; 

struct pixrect *pr; 

confirmer = window_create (0, FRAME, FRAME_SHOW_LABEL, FALSE, 0) ; 
panel = window_create (confirmer, PANEL, 0); 

message_item = panel_create_item (panel, PANEL_MESSAGE, 

PANE L_LABEL_STRI NG , message, 0) ; 

if (ok_only) { 

pr = panel_button_image (panel, "Continue", 8, 0); 
width = pr->pr_width; 

} else { 
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pr = panel_button_image (panel, "Cancel", 8, 0); 
width = 2 * pr->pr_width + 10; 

} 

/* center the yes/no or ok buttons under the message */ 
r = (Rect *) panel_get (message_item, PANEL_ITEM_RECT) ; 
left = (r->r_width - width) / 2; 
if (left < 0) 
left = 0; 

top = rect_bottom(r) + 5; 
if (ok_only) { 

panel_create_i tem{ panel , PANEL_BUTTON , 

PANEL_ITEM_X, left, PANEL_ITEM_Y, top, 

PANEL_LABEL_IMAGE , pr, 

PANEL_CLIENT_DATA, 1, 

PANEL_NOTIFY_PROC, yes_no_ok, 

0); 

1 else { 

panel_create_item( panel , PANEL_BUTTON, 

PANEL_ITEM_X, left, PANEL_ITEM_Y , top, 

P ANEL_LABEL_IMAGE , pr, 

PANEL_CLIENT_DATA, 0, 

PANEL_NOTIFY_PROC, yes_no_ok, 

0); 

panel_create_i tern ( panel , PANEL_BUTTON , 

PANEL_LABEL_IMAGE, panel_button_image (panel , "Confirm", 8, 0), 
PANEL_CLIENT_DATA, 1, 

PANEL_NOTIFY_PROC, yes_no_ok, 

0); 

1 

window_f it (panel) ; 
window_f it (confirmer) ; 

/* center the confirmer frame on the screen */ 
r = (Rect *) window_get (confirmer, WIN_SCREEN_RECT) ; 

width = (int) window_get (confirmer, WIN_WIDTH); 

height = (int) window_get (confirmer, WIN_HEIGHT); 

left = (r->r_width - width) / 2; 

top = (r->r_height - height) / 2; 

if (left < 0) 
left = 0; 
if (top < 0) 
top = 0; 

window_set (confirmer, WIN_X, left, WIN_Y, top, 0); 
return confirmer; 

1 

static void 

yes_no_ok ( item, event) 

Panel_item item; 

Event *event; 

{ 

window_return (panel_get ( item, PANEL_CLIENT_DATA) ) ; 

} 
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A.2. image browser _1 The following program is discussed in Chapter 4, Using Windows. It lets the 

user browse through icons and display them. It shows a more complex subwin- 
dow layout. 
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^★■fr*************************************************************************^ 

/* V 

/* image_browser_l . c */ 

/* V 

^***************************************************************************^ 
y'***************************************************************************^ 
/* */ 

/* This program allows the user to view the images in files generated by */ 

/* iconedit. image_browser_l displays a window with three sub-windows. */ 

/* The user must first press the List button to get a listing of the */ 

/* *.icon files. Next, the user selects a file containing an image and */ 

/* then presses the Show button to display the image. The subwindow */ 

/* layout places the tty subwindow to the left, the control panel to the */ 

/* upper right, and a panel which displays the image to the lower right. */ 

/* The user has the ability to close, move, resize, hide, redisplay, or */ 

/* quit the window. */ 

/* */ 



#include <suntool/sunview . h> 

#include <suntool/panel . h> 

#include <suntool/tty . h> 

#include <stdio.h> 

#include <suntool/icon_load . h> 

#include <suntool/seln . h> 

Frame frame; 

Panel control_panel , display_panel ; 

Tty tty; 

Panel_item dir_item, fname_item, image_item; 
ls_proc(), show_proc(), quit_proc(); 
char *get_selection ( ) ; 

#def ine MAX_PATH_LEN 1024 
#def ine MAX_F I LEN AME_LE N 256 
main(argc, argv) 
int argc; 
char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 
FRAME_LABEL, " image_browser_l " , 
0 ); 

inittty ( ) ; 
init_control_panel ( ) ; 
initdisplaypanel ( ) ; 
window_f it (frame) ; 
window_main_loop ( frame) ; 
exit (0) ; 

1 

init_tty ( ) 
t 

tty = window_create( frame, TTY, 

WIN_COLUMNS, 30, 

WIN_R0WS, 20, 

0 ); 

} 

init_control_panel ( ) 

{ 

char *getwd(); 
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char current_dir [ 1024 ] ; 

control_panel = window_create( frame, PANEL, 0); 

dir_item = panel_create_item(control_panel, PANEL_TEXT, 
PANEL_VALUE_DISPLAY_LENGTH, 13, 

PANEL_LABEL_STRING, "Dir: ", 

PANEL_VALUE , getwd ( current_dir ) , 

0); 

fname_item = panel_create_item (control_panel , PANEL_TEXT , 
PANEL_ITEM_X, ATTR_COL(0), 

PANEL_ITEM_Y, ATTR_ROW(l), 

PANEL_VALUE_DISPLAY_LENGTH, 13, 

PANEL_LABEL_STRING, "File : " , 

0); 

panel_create_item ( control_panel , PANEL_BUTTON, 

PANEL_ITEM_X, ATTR_COL(0), 

PANEL_I TEM_Y , ATTR_ROW ( 2 ) , 

PANEL_LABEL_IMAGE, panel_button_iinage ( control_panel , "List" ,0,0), 
PANEL_NOTIFY_PROC, ls_proc, 

0); 

panel_create_item(control_panel , PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image ( control_panel , "Show" ,0,0), 
PANEL_N0T IFY_PROC , show_proc , 

0); 

panel_create_i tem ( control_panel , PANEL_BUTTON , 

PANEL_LABEL_IMAGE , panel_button_image ( control_panel , "Quit" ,0,0), 
PANEL_NOTIFY_PROC , quit_proc, 

0); 

window_f it (control_panel) ; 



ls_proc ( ) 

{ 

static char previous_dir [MAX_PATH_LEN] ; 
char *current_dir ; 
char cmdstring [100] ; 

current_dir = (char *)panel_get_value(dir_item) ; 
if (strcmp (current_dir, previousdir ) ) { 
chdir (current_dir ) ; 

sprintf (cmdstring, "cd %s n" , current_dir ) ; 
ttysw_input( tty , cmdstring, strlen(cmdstring) ) ; 
strcpy (previousdir , currentdir) ; 

] 

sprintf (cmdstring, "Is -1 %s n", panel_get_value(fname_item) ) ; 
ttysw_input (tty, cmdstring, strlen (cmdstring) ) ; 

} 

quit_proc ( ) 

{ 

window_destroy (frame) ; 

} 

show_proc( ) 

{ 

char *filename; 

if (! strlen (f ilename = get_select ion ( ) ) ) 
return ; 

load_image( filename) ; 

1 

load_image( filename) 
char *filename; 
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{ 



Pixrect *image; 

char errormsg [ IL_ERRORMSG_SIZE] ; 
if (image = icon_load_mpr (filename, error_msg)) { 
panel_set ( image_item, 

PANEL_ITEM_X , ATTR_COL ( 5 ) , 

PANEL_ITEM_Y, ATTR_R0W(4), 

PANEL_LABEL_IMAGE , image, 

0 ); 

} 

} 

init_display_panel ( ) 
t 

display_panel = window_create ( frame, PANEL, 

WIN_BELOW, control_panel, 

WIN_RIGHT_OF , tty, 

0 ); 

image_item = panel_create_item (display_panel , PANEL_MESSAGE, 0) ; 

} 

char * 

get_selection ( ) 

{ 

static char filename [MAX_FILENAME_LEN] ; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire(SELN_PRIMARY) ; 

buffer = seln_ask ( ^holder , SELN_REQ_CONTENTS_ASC I I , 0, 0); 

strncpy (filename, buffer->data + sizeof (Seln_attribute) , MAX_FILENAME_LEN) ; 
return (filename); 

} 

«. > 
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A.3. image browser _2 The following program is discussed in Chapter 4, Using Windows . It is a more 

complex icon browser than the previous example It illustrate how you can use 
row/column space to specify the size of a subwindow. 
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#ifndef lint 

static char sccsid[] = "(3( # ) image_browser_2 . c 1.3 86/09/15 Copyr 1986 Sun Micro"; 
#endif 



^★**********************************************i****************************^ 

/* */ 

/* image_browser_2 . c */ 

/* V 

^***************************************************************************/ 
^***************************************************************************y 

/* V 

/* This program allows the user to specify a filename and push the Browse */ 

/* button which then displays the images in the files in a scrollable */ 

/* panel. This application illustrates how you can use row/column space */ 

/* to specify the size of a subwindow. The user also has the ability to */ 

/* close, move, resize, hide, redisplay, or quit the window. */ 

/* V 

/***************************************************************************^ 



#include <suntool/sunview. h> 

#include <suntool/panel . h> 

#include <suntool/tty . h> 

#include <stdio.h> 

#include <suntool/icon_load . h> 

#include <suntool/seln . h> 

/* used to expand shell command arguments */ 

#include <suntool/expand_name . h> 

#include <suntool/scrollbar . h> 
static char namebuf [ 100 ] ; 
static int file_count, image_count; 
static struct namelist *name_list; 

#define get_name(i) name_list->names [ ( i ) ] 

Frame frame; 

Panel control_panel , display_panel ; 

Tty tty; 

Panel_item dir_item, fname_item, image_item; 
show_proc(), browseproc ( ) , quit_proc(); 

Pixrect *get_image( ) ; 
char *get_selection ( ) ; 

#def ine MAX_PATH_LEN 1024 
#def ine MAX_FILENAME_LEN 256 
main(argc, argv) 
int argc; 
char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, " image_browser_2 " , 

0); 

ini t_control_panel ( ) ; 
init_display_panel ( ) ; 
window_set ( control_panel , 

WIN_WIDTH, window_get (display_panel , WIN_WIDTH, 0), 
0); 

window_f it (frame) ; 
window_main_loop ( frame) ; 
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] 



exit (0) ; 



init_control_panel ( ) 

t 

char current_dir [MAX_PATH_LEN] ; 

control_panel = window_create( frame, PANEL, 0); 

dir_item = panel_create_item(control_panel , PANEL_TEXT, 

PANEL_LABEL_X , ATTR_COL ( 0 ) , 

PANEL_LABEL_Y , ATTR_ROW ( 0 ) , 

PANEL_VALUE_DISPLAY_LENGTH, 23, 

PANEL_VALUE, getwd ( currentdir ) , 

PANEL_LABEL_STRING, "Dir: ", 

0); 

(void) panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE , panel_button_image ( control_panel , "Browse" ,0,0), 
PANEL_NOTIFY_PROC , browse_proc , 

0); 

fname_item = panel_create_item(control_panel, PANEL_TEXT, 

PANEL_LABEL_X , ATTR_C0L ( 0 ) , 

PANEL_LABEL_Y , ATTR_ROW ( 1 ) , 

PANEL_VALUE_DISPLAY_LENGTH, 23, 

PANEL_LABEL_STRING, "File:", 

0); 

(void) panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (control_panel , "Quit" ,6,0), 
PANEL_NOTIFY_PROC, quit_proc, 

0); 

window_f it_height (control_panel ) ; 

window_set (control_panel , PANEL_CARET_ITEM, fname_item, 0); 



brows e_proc ( ) 

{ 

Panel_item old_item; 
register int i; 
int len; 

Pixrect *image; 

int previous_image_count ; 

register int row, col; 
set_directory ( ) ; 
matchf iles ( ) ; 

panel_each_item(display_panel , old_item) 

pr_destroy ((Pixrect * )panel_get (old_item, PANEL_LABEL_IMAGE) ) ; 
panel_f ree (old_item) ; 
panel_end_each 

previous_image_count = image_count ; 

for (row = 0, imagecount = 0; image_count < file_count; row++) 
for (col = 0; col < 4 && image_count < file_count; col++) { 
if (image = get_image( image_count ) ) { 

panel_create_item (display_panel , PANEL_MESSAGE, 

PANEL_ITEM_Y, ATTR_R0W ( row) , 

PANEL_ITEM_X, ATTR_COL ( col ) , 

PANEL_LABEL_IMAGE, image, 0); 

image_count++ ; 

] 

} 

if (image_count <= previous_image_count ) 
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panel_update_scrolling_size(display_panel) ; 

panel_paint (display_panel , PANEL_CLEAR) ; 
f reenamelist (namelist ) ; 

1 

setdirectory ( ) 

{ 

static char previousdir [MAX_PATH_LEN] ; 
char *current_dir ; 

current_dir = (char * ) panel_get_value (dir_item) ; 
if ( strcmp ( current_dir, previousdir ) ) { 
chdir (current_dir ) ; 
strcpy (previousdir , current_dir) ; 

1 

] 

Pixrect * 
get_image ( i ) 
int i; 

{ 

char error_msg [ IL_ERRORMSG_SI ZE] ; 

return (icon_load_mpr (get_name(i) , error_msg ) ) ; 

} 

match_f iles ( ) 

{ 

char *val; 

val = (char *)panel_get_value(fname_item) ; 
strcpy (namebuf , val); 

/* used to expand shell command arguments */ 

name_list = expand_name ( namebuf ) ; 
file_count = name_list->count ; 

1 

quit_proc ( ) 

{ 

window_destroy ( frame) ; 

1 

show_proc ( ) 

{ 

char *filename; 

if ( !strlen( filename = get_selection ( ) ) ) 
return; 

load_image(f ilename) ; 

1 

load_image( filename) 
char *filename; 

{ 

Pixrect *image; 

char error_msg [ IL_ERRORMSG_SIZE] ; 
if (image = icon_load_mpr ( filename , error_msg)) { 
panelset ( imageitem, 

PANEL_ITEM_X, ATTR_C0L(5), 

PANEL_ITEM_Y , ATTR_R0W(4), 

PANEL_LABEL_IMAGE/ image, 

0 ); " 

} 

1 

init_display_panel ( ) 
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int width; 

Scrollbar sb = scrollbar_create(SCROLL_MARGIN, 10 , 0 ) ; 
width = ( int ) scrollbar get ( sb , SCROLL_THICKNESS, 0); 
displaypanel = window_create( frame, PANEL, 



WIN_BEL0W, control_panel , 

WIN_X, 0, 

WI NVERTI CAL_SCROLLB AR , sb, 

WINROWHEIGHT, 64, 

WIN_COLUMN_WIDTH, 64, 

WIN_ROW_GAP, 10, 

WIN_COLUMN_GAP, 10, 

WIN_LEFT_MARGIN, width + 10, 

WIN_TOP_MARGIN , 10, 

WIN_ROWS, 4, 

WIN_COLUMNS, 4, 

0 ); 

window_set (display_panel , WIN_LEFT_MARGIN , 10, 0); 



64, 

64, 

10 , 

10 , 

width + 10, 



char * 

getselection ( ) 

{ 

static char f ilename[MAX_FILENAME_LEN] ; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire (SELN_PRIMARY) ; 

buffer = seln_ask (&holder , SELN_REQ_CONTENTS_ASCII , 0, 0); 

strncpy (filename, buffer->data + sizeof (Seln_attribute) , MAX_FILENAME_LEN) ; 
return (filename); 
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A.4. tty jo The following program demonstrates the use of ttysw_input ( ) , 

ttysw_output ( ) and TTY escape sequences. These functions are explained 
in Chapter 11, 77 Y Subwindows. 

tty jo creates a panel and a tty subwindow. You can send arbitrary character 
sequences to the latter as input or output by manipulating panel items. There is 
also a button that sends the current time within the escape sequence to set the 
frame label. Try sending different sequences to the tty subwindow. Press 
CTRL-R to see the difference between what appears on the screen and what was 
input to the pseudo-tty. Also try starting the tool with a program such as vi as a 
command line argument. 
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/*****************************************************************************^ 
#ifndef lint 

static char sccsid[] = "(§(#) tty_io. c 1.4 87/11/19 Copyr 1986 Sun Micro"; 

#endif 

/*****************************************************************************/ 

^******#**********************************************************************^ 

/* V 

/* tty_io.c */ 

/* V 

/*****************************************************************************^ 
^z*****************************************************************************/ 

/* V 

/* This application creates a panel and a tty subwindow. The user can */ 

/* manipulate the input text and the output text panel items. The user can */ 

/* also display the current time in the frame header. The user has the */ 

/* ability to send different sequences to the tty subwindow. The user for */ 

/* instance has the capability to invoke the vi editor. The user can also */ 

/* close, move, resize, hide, redisplay, or quit the window. */ 

/* V 

^*****************************************************************************^/ 

#include <stdio.h> 

#include <suntool/sunview . h> 

#include <suntool/tty . h> 

#include <suntool/panel . h> 

#def ine TEXT_ITEM_MAX_LENGTH 25 
Tty tty; 

Panel_item text_item; 

char tmp_buf[80]; 

static void input_text ( ) ; 

static void output_text ( ) ; 

static void output_time( ) ; 

main(argc, argv) 

int argc; 

char **argv; 



Frame frame; 

Panel panel; 

frame = window_create(NULL, FRAME, 

FRAME_ARGS , argc, argv, 

WIN_ERROR_MSG, "Can't create tool frame", 

0 ); 

panel = window_create( frame, PANEL, 0); 

/* set up a simple panel subwindow */ 
panel_create__item (panel , P ANEL_BUT TON , 

PANEL_LABEL_IMAGE, panel_button_image (panel , "Input text", 11, 0), 
PANEL_NOTIFY_PROC, input_text, 

0 ); 

panel_create_item (panel, PANEL_BUTTON, 

P ANEL_LABEL_IMAGE , panel_button_image ( panel , "Output text", 11, 0), 
P AN EL_NO T I FY_P ROC , output_text, 

0 ); 

text_item = panel_create_item( panel, PANEL_TEXT, 

PANEL_LABEL_STRI NG , " Text : " , 

PANEL_VALUE, "Hello hello", 

PANEL_VALUE_DISPLAY_LENGTH, TEXT_ITEM_MAX_LENGTH, 

0 ); 
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panel_create_item (panel , PANEL_BUTTON , 

PANEL_LABEL_IMAGE, panel_button_image ( panel , "Show time", 11, 0), 
PANEL_NOTIFY_PROC , output_t ime , 

0 ) ; 

window_f itheight (panel ) ; 

/* Assume rest of arguments are for tty subwindow, except FRAMEARGS leaves the 
* program_name as argv[0], and we don't want to pass this to the tty subwindow. 

*/ 

argv++; 

tty = window_create( frame, TTY, 

TTYARGV, argv, 

WIN_ROWS, 24, 

WIN_COLUMNS, 80, 

0 ); 

window_f it (frame) ; 

ttysw_input (tty , "echo my pseudo-tty is 'tty' n", 28); 
window_main_loop( frame) ; 
exit ( 0 ) ; 

} 

static void 

input_text(item, event) 

Panel_item item; 

Event *event; 

{ 

strcpy (tmp_buf , (char *) panel_get_value (text_item) ) ; 
ttysw_input (tty , tmp_buf, strlen (tmp_buf ) ) ; 

} 

static void 

output_text ( item, event) 

Panel_item item; 

Event *event; 

{ 

strcpy (tmp_buf , (char *) panel_get_value (text_item) ) ; 
ttysw_output (tty, tmp_buf, strlen ( tmp_buf ) ) ; 



static void 

output_t ime ( item, event) 

Panel_item item; 

Event *event; 

t 

#include <sys/time.h> 

#def ine ASCTIMELEN 26 

struct timeval tp; 

/* construct escape sequence to set frame label */ 
tmp_buf[0] = ' 033'; 
tmp_buf [1] = ' ] ' ; 
tmp_buf [2] = ' 1 ' ; 

tmpbuf [ 2 + ASCTIMELEN + 1] = ' 033'; 
tmp_buf [ 2 + ASCTIMELEN + 2] = ' '; 

gettimeofday ( &tp , NULL); 

strncpy (&tmp_buf [3 ] , ctime(&tp. tv_sec) , ASCTIMELEN); 
ttysw_output (tty , tmp_buf, ASCTIMELEN + 5); 
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A.5. font menu The next program, fon tjnenu, builds on several of the examples given in Chapter 

12, Menus. Examples of the font menu it creates are shown below: 



Frame 


=> tg 








Courier 


=*> 


i 


Si ze 


Serif 




1 


Bold 
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Itali c 




8 




CMR 


18 






12 




Screen 


14 








LO 






18 



Frame =*■ b 
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Bold 


18 


Italic 
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14 




16 




18 
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y^*****************************************************************************y' 

#ifndef lint 

static char sccsid[] = "@( # ) font_menu . c 1.2 86/09/15 Copyr 1986 Sun Micro"; 
#endif 

y*****************************************************************************y 

/* V 

/* font_menu.c */ 

/* V 

y*****************************************************************************y 

y*****************************************************************************y 

y*****************************************************************************^ 
/* */ 

/* This program gives the user the ability to display pull-right menus to */ 
/* select various menu items. The first menu allows the user to select */ 

/* either the frame, family, size, bold, or italic menu items. For example, */ 
/* if you select the family menu item you can then proceed by selecting both */ 
/* the font family and a point size within the family. The font family and */ 
/* and the point size within the family will be displayed in the upper-hand */ 

/* corner of the canvas . */ 

/* */ 



y*****************************************************************************y 
#include <suntool/sunview . h> 

#include <suntool/panel . h> 

#include <suntool/walkmenu . h> 

void set_family ( ) , set_size(), set_on_of f ( ) , toggle_on_of f ( ) , open_fonts ( ) ; 

Menu new_menu(), initialize_on_of f ( ) ; 
char *int_to_str ( ) ; 
extern char * sprintf(); 
extern char * malloc(); 

Panel_item f eedback_item; 

char *family, *size, *bold, *italic; 

Pixfont *cour, *serif, *apl, *cmr, *screen; 

y******************************** , *********************************************y 



/* main */ 
/* First create the base frame, the feedback panel and feedback item. The */ 
/* feedback item is initialized to "gallant 8". */ 
/* Then get the frame's menu, call new_menu ( ) to create a new menu with the */ 
/* original frame menu as a pullright, and give the new menu to the frame. */ 



main(argc, argv) 
int argc; 
char *argv[]; 

{ 

Frame frame; 

Panel panel; 

Menu menu; 
int defaults; 



frame = window_create(NULL, FRAME, FRAME_LABEL, "Menu Test -- 
panel = window_create ( frame, PANEL, WIN_ROWS, 1, 0); 
f eedback_item = panel_create_i tern ( panel , PANEL_MESSAGE, PANEL 
family = "Gallant", size = "8", bold = italic = ""; 
update_f eedback ( ) ; 



Try frame menu." 
LABEL_STRING , "" 



0 ); 

0 ); 



/* remember if user gave -d flag */ 

if (argc >= 2) defaults = strcmp ( argv [ 1 ] , "-d") == 0; 
menu = (Menu ) window_get (frame, WIN_MENU) ; 
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menu = new_menu (menu , defaults); 
window_set (frame, WIN_MENU, menu, 0); 

window_main_loop (frame) ; 

) 

^*****************************************************1lr***********************^/ 

/* newmenu -- returns a new menu with 'original menu' as a pullright. */ 

/*****************************************************************************^/ 

Menu 

newmenu (original_menu , defaults ) 

Menu original_menu; 
int defaults; 

{ 

Menu new_menu, family_menu, sizemenu, on_off_menu; 
int i ; 



/* create the on-off menu, which will be used as a pullright 
* for both the bold and italic items to the new menu. 



V 



on_off_menu = menu_create (MENU_STRING_ITEM, "On", 1, 

MENU_STRING_ITEM, "Off", 0, 

MENU_GEN_PROC , initial i ze_on_o f f , 

MENU_NOTIFY_PROC, set_on_off, 

0 ); 

/* create the new menu which will eventually be returned */ 
open_f onts ( ) ; /* first open the needed fonts */ 
new_menu = menu_create( 

MENU_PULLRIGHT_ITEM, 

" Frame" , 
original_menu, 

MENU_PULLRIGHT_I TEM , 

"Family" , 

family_menu = menu_create( 



MENU_ITEM, 

MENU_STRING , 
MENU_F0NT , 

0 , 

MENU__ITEM, 

MENU_STRING , 
MENU_F0NT , 

0 , 

MENU_ITEM, 

MENU_STRING, 

MENU_FONT, 

0 , 

MENU_ITEM, 

MENU_STRING, 
MENU_F0NT , 

0, 



"Courier" , 
cour , 



"Serif" , 
serif, 



" aplAPLGIJ" , 
apl, 



" CMR " , 
cmr, 



MENU_ITEM, 

MENU_STRING , "Screen", 
MENU_F0NT, screen, 

0 , 

MENU_NOTIFY_PROC, set_family, 

0 ), 

MENU_PULLRIGHT_I TEM , 
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"Size", size_menu 

MENU_ITEM, 
MENU_STRING, 
MENU_PULLRIGHT , 
MENU_NOTIFY_PROC, 
MENU_CLIENT_DATA, 
0 , 

MENU_ITEM, 
MENU_STRING , 
MENU_PULLRIGHT , 
MENU_NO T I FY_PROC , 
MENU_CLIENT_DATA , 
0 , 



= menu_create ( 0 ) , 

"Bold", 
on__of f_menu , 
toggleonof f , 
Sbold, 



"Italic" , 
on_of f_menu, 
toggle_on_of f , 
&italic. 



0 ); 

/* give each item in the family menu the size menu as a pullright */ 
for (i = ( int )menu_get ( family_menu, MENU_NITEMS ) ; i > 0; --i) 
menu_set (menu_get (family_menu, MENU_NTH_ITEM, i), 

MENU_PULLRIGHT, size_menu, 0); 



/* put non-selectable lines inbetween groups of items in family menu */ 
menu_set ( f amily_menu, 

MENU_INSERT, 2, menu_create_item (MENU_STRING , " ", 

MENU_INACTIVE, TRUE, 

0 ), 

0 ); 

menu_set (family_menu, 

MENU_INSERT, 5, menu_get ( f amily_menu , MENU_NTH_ITEM, 3), 

0 ); 



/* The size menu was created with no items. Now give it items representing */ 
/* the point sizes 8, 10, 12, 14, 16, and 18. */ 

for ( i = 8 ; i <= 18 ; i += 2 ) 

menu_set (size_menu, MENU_STRING_ITEM, int_to_str ( i ) , i, 0); 

/* give the size menu a notify proc to update the feedback */ 
menu_set (size_menu, MENU_NOTIFY_PROC , set_size, 0); 

/*• if the user did not give the -d flag, make all the menus come 

* up with the initial and default selections the last selected 

* item, and the initial selection selected. 

V 

if ( ! defaults ) { 

menuset (new_menu, 

MENU_DEFAULT_SELECTION, MENU_SELECTED , 

MENU_INITIAL_SELECTION, MENU_SELECTED , 
MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ) ; 

menuset ( f amily_menu , 

MENU_DEFAULT_SELECTION, MENU_SELECTED , 

MENU_INITIAL_SELECTION, MENU_SELECTED , 
MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ); 

menu_set (size_menu, 

MENU_DEFAULT_SELECT I ON , MENU_SELECTED , 

MENU_INITIAL_SELECTION, MENU_SELECTED , 
MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ) ; 

menu_set (on_of f_menu, 

MENU_DEFAULT_SELECTION , MENU_SELECTED , 
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MENU_INITIAL_SELECTION, MENU_SELECTED , 
MENU_ INI T I AL_SELEC T I ON_SELECTED , TRUE , 
0 ); 

} 

return (new_menu); 

} 



/* set_family -- notify proc for family menu. Get the current family and */ 
/* display it in the feedback panel. Note that we first get the value */ 
/* of the menu item. This has the side effect of causing any pullrights */ 
/* further to the right of mi to be evaluated. Specifically, the value of */ 
/* each family item is the value of its pullright -- namely the size menu. */ 
/* When the size menu is evaluated, the notify proc set_size() is called, */ 
/* which updates the feedback for the size. */ 



y*****************************************************************************y 

/*ARGSUSED*/ 

void 

setfamily (m, mi) 

Menu m; 

Menu_item mi; 

[ 

menu_get(mi, MENU_VALUE) ; /* force pullrights to be evaluated */ 

family = menu_get(mi, MENU_STRING) ; 
update_f eedback ( ) ; 

1 

y*****************************************************************************y 
/* set_size -- notify proc for the size menu. */ 

/*ARGSUSED*/ 

void 

set_size(m, mi) 

Menu m; 

Menu_item mi; 

{ 

size = menu_get(mi, MENU_STRING) ; 
update_f eedback ( ) ; 

] 

y****************************************************************************y 



/* initialize_on_of f -- generate proc for the on_off menu. */ 
/* The on-off menu is a pullright of both the bold and the italic menus. */ 
/* We want it to toggle -- if its parent was on, it should come up with */ 
/* "Off" selected, and vice-versa. We can do that by first getting the */ 
/* parent menu item, then, indirectly through its client data attribute, */ 
/* seeing if the string representing the bold or italic state is null. */ 
/* If the string was null, we set the first item ("On") to be selected, */ 
/* else we set the second item ("Off") to be selected. */ 



y*****************************************************************************^ 

Menu 

initialize_on_of f (m, op) 

Menu m; Menu_generate op; 

( 

Menu_item parent_mi; 
char **name; 

if (op ! = MENU_DISPLAY) return (m) ; 

parent_mi = (Menu_item)menu_get (m, MENU_PARENT) ; 

l , 
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name = (char ** )menu_get (parent_mi , MENU_CLIENT_DATA) ; 
if ( **name == NULL) 

menu_set (m, MENU_SELECTED / 1, 0); 

else 

menuset (m, MENUSELECTED, 2 , 0); 
return (m) ; 

} 

/*************★*****★************************************★******************•** f 



/* set_on_off -- notify proc for on-off menu. */ 
/* Set the feedback string -- italic or bold -- appropriately depending on */ 
/* the current setting. Note that the "On" item was created to return a */ 
/* value of 1, and the "Off" item will return a value of 0 . */ 



/***************************************************************************** j 

void 

set_on_of f (m, mi) 

Menu m; Menu__item mi; 

[ 

Menu_item parent_mi; 
char **name; 

parent_mi = (Menu_item)menu_get (m, MENU_PARENT ) ; 
name = (char **)menu_get (parent_mi, MENU_CLIENT_DATA) ; 
if (menu_get (mi , MENU_VALUE) ) 

*name = (char *)menu_get (parent_mi , MENU_STRING) ; 

else 

*name = 

update_f eedback ( ) ; 

} 

/* toggle_on_of f -- notify 
/* Using a notify proc for 
/* up the on-off pullright 

/********★****★*********** 

/*ARGSUSED*/ 
void 

toggleonof f (m, mi) 

Menu m; 

Menuitem mi; 

{ 

char **name; 

name = (char **)menu_get (mi, MENU_CLIENT_DATA) ; 
if (**name == NULL) 

*name = (char * ) menuget (mi , MENU_STRING) ; 

else 

*name = ""; 
update_f eedback ( ) ; 

} 

update_feedback ( ) 

{ 

char buf [ 30 ] ; 

sprintf(buf, "%s %s %s %s", bold, italic, family, size); 
panel_set ( feedback_item, PANEL_LABEL_STRING , buf, 0); 

1 

char * 

int_to_str ( n) 

v , 



proc for the "Bold" and "Italic" menu items. */ 

the menu item allows toggling without bringing */ 

*/ 
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char *r = malloc(4); 
sprintf(r, "id", n); 
return (r) ; 

1 

void 

open_fonts ( ) 
t 

cour = pf_open ( "/usr/lib/fonts/f ixedwidthfonts/cour . r . 10" ) ; 

' serif = pf_open { "/usr/lib/fonts/f ixedwidthfonts/serif . r . 10 ") ; 
apl = pf_open ( "/usr/lib/fonts/f ixedwidthfonts/apl . r . 10" ) ; 
cmr = pf_open ( "/usr/lib/fonts/f ixedwidthfonts/cmr . b . 8" ) ; 
screen = pf_open ( "/usr/lib/fonts/f ixedwidthfonts/screen . r . 11" ) ; 
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A.6. resize _demo This program demonstrates how to resize the subwindows of a frame yourself if 

you need to use a complicated topology. 

The particular subwindow layout used here has four subwindows. One has a 
fixed width and height in pixels, another has a fixed width in characters (using 
the user-set default font), and the other two fill up the empty space. One of the 
subwindows also has a scrollbar. 

This program interposes in front of the frame’s client event handler. If the event 
is WIN RESIZE, the program’s own resize ( ) procedure is called, which sets 
the subwindow positions explicitly. 

For a discussion of interposing and the Notifier, see Chapter 17, The Notifier. 

The simpler case of using window attributes to layout subwindows is described 
under Explicit Subwindow Layout in Chapter @NumberOf(window), 

@TitleOj\ window ). 
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#ifndef lint 

static char sccsid[] = "@( # ) resize_demo . c 1.3 88/03/14 Copyr 1986 Sun Micro"; 
#endif 



/* */ 

/* resize_demo . c */ 

/* V 

^***************************************************************************^/ 

/* V 

/* This application allows the user to resize the subwindows of a frame. */ 

/* This subwindow layout consists of four subwindows . One of the */ 

/* subwindows has a fixed width and heigth in pixels. Another subwindow */ 
/* has a fixed width in characters. The final two subwindows fill up the */ 
/* empty space. The user also has the ability to close, move, resize, hide*/ 
/* redisplay, or quit the window. */ 

/* V 

^***************************************************************************^/ 



#include <suntool/sunview. h> 

#include <suntool/canvas . h> 

#include <suntool/scrollbar . h> 

Canvas Canvas_l, Canvas_2, Canvas_3, Canvas_4; 
Pixwin *Pixwin_l, *Pixwin_2, *Pixwin_3, *Pixwin_4; 
Rect framerect; 

PIXFONT *font; 



extern char * sprintf(); 

/* 

* font macros: 

font_off set ( font ) gives the vertical distance between 

the font origin and the top left corner 
of the bounding box of the string displayed 
(see Text Facilities for Pixrects in the 
Pixrect Reference Manual) 
font_height (font ) gives the height of the font 

*/ 

#define font_offset (font) 

#define font_height ( font ) 

/* 

* SunView-dependent size definitions 

V 

#def ine LEFT_MARGIN 5 

^define RIGHT_MARGIN 5 

#def ine BOTTOMMARGIN 5 

#def ine SUBWINDOW SPACING 5 



( - font- >pf char [ 'n' ] . pchome.y) 
( font ->pf_default size . y ) 



/* 

/* 

/* 

/* 



margin on left side of frame */ 
margin on right side of frame */ 
margin on bottom of frame */ 
space in between adjacent 
subwindows */ 



/* 



* application-dependent size definitions 

V 

#def ine CANVAS_1_WIDTH 320 /* 

#def ine CANVAS_1_HEIGHT 160 /* 

#def ine CANVAS_3_C0LUMNS 30 /* 

main(argc, argv) 
int argc; 
char **argv; 



width in pixels of canvas 1 */ 
height in pixels of canvas 1 */ 
width in characters of canvas 3 
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Frame frame; 

static Notify_value catch_resize( ) ; 

static void draw_canvas_l ( ) , draw_canvas_3 ( ) ; 

/* 

* create the frame and subwindows, and open the font 

* no size attributes are given yet 
*/ 

frame - window_create (NULL, FRAME, 

FRAME_ARGS, argc, argv, 

WIN_ERROR_MSG, "Can't create tool frame", 

FRAME_LABEL, "Resize Demo" , 

0 ); 

Canvas_l = window_create ( frame, CANVAS, 

CANVAS_RESIZE_PROC , draw_canvas_l , 

0 ) ; 

Canvas_2 = window_create( frame, CANVAS, 

o ) ; 

Canvas_3 = window_create ( frame , CANVAS, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create ( 

SCROLLJPLACEMENT, SCROLL_EAST , 

0 ), 

CANVAS_RESIZE_PROC , draw_canvas_3 , 

0 ) ; 

Canvas_4 = window_create ( frame, CANVAS, 

0 ); 

Pixwin_l = canvas_pixwin (Canvas_l ) ; 

Pixwin_2 = canvas_pixwin (Canvas_2 ) ; 

Pixwin_3 = canvas_pixwin (Canvas_3 ) ; 

Pixwin_4 = canvas_pixwin (Canvas_4 ) ; 
font = pf_default ( ) ; 

/* 

* now that the frame and font sizes are known, set the initial 

* subwindow sizes 
*/ 

resize( frame) ; 

/* 

* insert an interposer so that whenever the window changes 

* size we will know about it and handle it ourselves 
*/ 

(void) notify_interpose_event_f unc (frame, catch_resize, NOTIFYSAFE) ; 
/* 

* start execution 

V 

window_main_loop ( frame) ; 
exit ( 0) ; 



* catchresize 

★ 



interposed function which checks all input events passed to the frame 
for resize events; if it finds one, resize () is called to refit 
the subwindows; checking is done AFTER the frame processes the 
event because if the frame changes its size due to this event (because 
the window has been opened or closed for instance) we want to fit 
the subwindows to the new size 



V 

static Notify_value 
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catch_resize(frame, event, arg, type) 

Frame frame; 

Event * event; 

Notify_arg arg; 

Notify_event_type type; 

t 

Notify_value value; 

value = notify_next_event_func( frame, event, arg, type); 
if (event_act ion (event) == WINRESIZE) 
resize (frame) ; 
return (value) ; 



* fit the subwindows of the frame to its new size 

V 

resize( frame) 

Frame frame; 
t 

Rect *r; 

int canvas_3_width; /* the width in pixels of canvas 3 */ 

int stripeheight ; /* the height of the frame's name stripe */ 

/* if the window is iconic, don't do anything */ 
if (( int )window_get (frame, FRAME_CLOSED) ) 
return ; 

/* find out our new size parameters */ 
r = (Rect *) window_get( frame, WIN_RECT); 
framerect = *r; 

stripeheight = (int) window_get (frame, WIN_TOP_MARGIN) ; 
canvas_3_width = CANVAS_3_C0LUMNS * font- >pf_def aultsize . x 
+ (int) scrollbar_get (SCROLLBAR, SCROLL_THICKNESS) ; 
window_set (Canvas_2 , 

WIN_X, 0, 

WIN_Y, 0, 

WIN_WIDTH, framerect . r_width - canvas_3_width 

- LEFT_MARGIN - SUBWINDOWS PACING 

- RIGHTMARGIN, 

WIN_HEIGHT , framerect . r_height - CANVAS_1_HEIGHT 

- stripeheight - SUBWINDOW_SPACING - 
BOTTOM MARGIN, 



WIN HEIGHT, 



0 ); 

windowset (Canvas_l , 
WIN_X, 

WIN_Y , 

WIN_WIDTH , 
WIN_HEIGHT, 
0 ); 

window_set (Canvas_4 , 
WIN_X, 

WIN_Y , 

WIN WIDTH, 



WIN_HEIGHT, 

0 ); 



framerect .rheight - CANVAS1HEIGHT 
SUBWINDOWSPACING - stripeheight, 
CANVAS_1_WIDTH, 

CANVAS 1 HEIGHT, 



CANVAS_1_WIDTH + SUBWINDOW_SPACING , 
framerect .r_height - CANVAS_1_HEIGHT 

- SUBWINDOWSPACING - stripeheight, 
f ramerect . r_width - canvas_3_width 

- CANVAS_1_WIDTH - LEFT_MARGIN 

- 2 * SUBWINDOW_S PACING - RIGHT_MARGIN , 
CANVAS 1 HEIGHT, 



sun 

microsystems 



Revision A, of March 27, 1990 




Appendix A — Example Programs (resize jiemo) 393 



window_set (Canvas_3 , 
WIN_X, 

WIN_Y, 
WIN_WIDTH , 
WIN HEIGHT , 



framerect . r_width - canvas_3_width 

- LEFT_MARGIN - SUBWINDOW_SPACING, 

0 , 

canvas_3_width, 

framerect . r_height - stripeheight 

- BOTTOM MARGIN, 



/* 

* draw_canvas_l 
*• draw_canvas_3 

* 

* draw simple messages in the canvases 

V 

static void 
draw_canvas_l ( ) 

( 

char buf [64] ; 

sprintf(buf, "%d by %d pixels", 

CANVAS_1_WIDTH , CANVAS_1_HEIGHT ) ; 
pw_text (Pixwin_l, 5, font_off set ( font ) , PIX_SRC, font, 

"This subwindow is always "); 

pw_text(Pixwin_l, 5, font_off set (font) + font_height (font) , 

PIX_SRC, font, buf); 



static void 
draw_canvas_3 ( ) 
{ 



char buf [ 64 ] ; 

sprintf(buf, "%d characters wide", 

CANVAS_3_COLUMNS) ; 

pw_text(Pixwin_3, 5, font_offset (font) , PIX_SRC, font, 

"This subwindow is always "); 

pw_text (Pixwin_3, 5, font_off set (font) + font_height (font ) , PIX_SRC, 

font, buf); 
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A.7. detool detool is a simple reverse-polish notation calculator which demonstrates how to 

use pipes to write a SunView-based front end for an existing non-SunView pro- 
gram. detool consists of a panel with buttons for each digit, the four arithmetic 
operations, and an enter key. The digits you hit are displayed in a message item 
and are sent via a pipe to ,dc(l) a UNIX desk calculator. When dc computes an 
answer, it is sent back to detool via a second pipe and it is displayed. 

Note also the use of a single notify procedure for all of the digit buttons. The 
actual digit associated with each button is stored as the client data for each panel 
item, so the notify procedure can determine which button was pressed by looking 
at the client data. This value is then passed directly to dc. The operation buttons 
also all use a single notify procedure. 

When you run detool, remember that it is a reverse-polish notation calculator. 

For instance, to compute 3*5 you must hit the buttons 3, Enter, 5, and * in that 
order. If you prefer infix notation, you could easily adapt detool to use bc(l) 
instead of dc. 
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#ifndef lint 

static char sccsid[] = "@( # )dctool . c 1.4 86/09/15 Copyr 1986 Sun Micro"; 
#endif 



/****************************************************************y 

/* V 

/* dctool.c */ 
/* */ 
/*★**★**********★**********★**★****★*****★****************★****★* y 
^/****************************************************************y 

/* V 
/* This program displays a simple reverse-polish notation */ 
/* calculator. This tool consists of a panel of buttons for */ 
/* each digit, the four arithmetic operations, and an enter key.*/ 
/* The numbers are displayed at the lower left-hand corner of */ 
/* the reverse-polish notation calculator below the button zero.*/ 
/* To compute 3*6 you must press the buttons 3, Enter, 6, and */ 
/* * in that order. When using the other three arithmetic */ 
/* operations follow the same order of sequence. */ 
/* */ 






/ 



#include <stdio.h> 

#include <suntool/sunview . h> 

#include <suntool/panel . h> 
static Frame frame; 

static Panel panel; 

static Panel_item digit_item[10 ] , enter_item; 

static Panel_item add_item, sub_item, mul_item, div_item; 

static Panel_item display_item; 

static char display_buf [ 512 ] = /* storage for the 

* numbers currently on 

* the display (stored as 

* a string) */ 



static 


FILE 


*fp_tochild; 


/* 


fp of pipe to child (write 








* 


data on it) */ 


static 


FILE 


*fp_f romchild; 


/* 


fp of pipe from child (read 








★ 


data from it) */ 


static 


int 


tochild; 


/* 


associated file descriptors */ 


static 


int 


f romchild; 






static 


int 


childpid; 


/* 


pid of child process */ 


static 


int 


dead = 0; 


/* 


set to 1 if child process has 








★ 


died */ 


main(argc. 


argv) 






int 


arge ; 






char 


**argv; 







static Notify_value pipe_reader ( ) ; 

static Notify_value dead_child ( ) ; 

frame = window_create ( (Window) NULL, FRAME, 

FRAME_ARGS, arge, argv, 

WIN_ERROR_MSG, "Cannot create frame", 
FRAME_LABEL, "detool - RPN Calculator", 
0 ); 

panel = window_create(frame, PANEL, 

0 ); 
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create_panel_items ( panel ) ; 
window_f it (panel) ; 
window_f it ( frame) ; 

/* start the child process and tell the notifier about it */ 
start_dc ( ) ; 

/* 

* note that notify_set_input_func takes a file descriptor, 

* not a file pointer used by the standard I/O library 

V 

(void) notify_set_input_f unc (frame, pipe_reader, fromchild); 
(void) not ify_set_wait3_f unc (frame, dead_child, childpid); 
window_main_loop (frame) ; 
exit (0) ; 

] 

static 

create_panel_i terns (panel ) 

Panel panel; 

{ 

int c; 

char name[2]; 

static void digit_proc ( ) , op_proc(); 

static struct { 

int col, row; 

) positions [ 10 ] = { 



o, 3 ], { 


o, 


0 }, { 


6, 


0 




{ 


12, 0 


}, 


{ 


o, 


1 }, { 


6, 


1 


}, 


{ 


12, 1 


}, 


{ 

]; 


o, 


2 }, { 


6, 


2 


}, 


{ 


12, 2 


} 



name [ 1 ] = ' ' ; 

for (c = 0; c < 10; C++) { 
name [ 0 ] = c + ' 0 ' ; 

digit_item [c] = panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image ( panel , name, 3, 0), 
PANEL_NOTIFY_PROC, digit_proc, 

PANEL_CLIENT_DATA, (caddr_t) (c + '0'), 

PANEL_LABEL_X, ATTR_C0L (positions [ c] .col), 

PANEL_LABEL_Y , ATTR_R0W ( posit ions [ c] .row), 

0); 

] 

add_item = panel_create_item( panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE , panel_button_image (panel , "+", 3, 0), 
PANEL_NOTIFY_PROC, op_proc, 

PANEL_CLIENT_DATA, (caddr_t) ' + ', 

PANEL_L ABEL_X , ATTR_C0L ( 18 ) , 

PANEL_LABEL_Y , ATTR_R0W ( 0 ) , 

0); 

sub_item = panel_create_item( panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE , panel_button_image ( panel , 3, 0), 

PANEL_NOT I FY_PROC , op_proc , 

PANEL_CLIENT_DATA , ( caddr_t ) , 

PANEL_LABEL_X , ATTRCOL ( 1 8 ) , 

PANEL_LABEL_Y , ATTR_R0W(1), 

0 ); 

mul_item = panel_create_item( panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE , panel_button_image(panel , 3, 0), 

PANEL_NOTIFY_PROC , op_proc, 

PANEL_CLIENT_DATA, (caddr_t) , 

PANEL_LABEL_X, ATTR_C0L ( 18) , 
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PANEL_LABEL_Y , ATTR_ROW ( 2 ) , 

0 ) ; 

div_item = panel_create_item( panel, PANEL_BUTTON , 

PANEL_LABEL_IMAGE , panel_button_image ( panel , "/", 3, 0), 
PANEL_NOT IFY_PROC , op_proc , 

PANEL_CLIENT_DATA , (caddr_t) '/' / 

PANEL_LABEL_X , ATTR_COL (18), 

PANEL_LABEL_Y , ATTR_ROW ( 3 ) , 

0); 

enter_item = panel_create_item ( panel , PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel , "Enter", 7, 0), 
PANEL_NOTIFY_PROC, op_proc, 

PANEL_CLIENT_DATA , (caddr_t) ' ', 

PANEL_LABEL_X , ATTR_COL ( 6 ) , 

PANEL_LABEL_Y , ATTR_ROW ( 3 ) , 

0); 

display_item = panel_create_item(panel , PANEL_MESSAGE , 
PANEL_LABEL_STRING, "0", 

PANEL_LABEL_X , ATTR_COL ( 0 ) , 

PANEL_LABEL_Y, ATTR_R0W(4), 

0); 

1 

/* callback procedure called whenever a digit button is pressed */ 
static void 



digit_proc ( item, 
Panel_item 
Event 

{ 

int 



event) 
item; 
*event ; 

digit_name 



char buf [2] ; 

buf[0] = digit_name; 
buf [1] = ' 



= (int) panel_get ( item, 

PANEL_CLIENT_DATA) ; 

/* display digit */ 



(void)strcat (display_buf , buf); 

panel_set (display_item, PANEL_LABEL_STRING , display_buf, 0); 
send_to_dc (digit_name) ; /* send digit to dc */ 



/* 

* callback procedure called whenever an operation button is 

* pressed 



V 

static void 
op_proc ( item, event) 

Panel_item item; 

Event *event; 

{ 

int op_name = (int) panel_get ( item, 

PANEL_CLIENT_DATA) ; 

display_buf [0 ] = ' '; /* don't erase display yet; wait 

* until the answer comes back */ 

send_to_dc (op_name) ; 
if (item != enter_item) 

send_to_dc( 'p' ) ; /* send a p so the answer will be 

* printed by dc */ 

send_to_dc ( ' 0 ) ; 

1 

/* 

* start the child process 




sun 

microsystems 



Revision A, of March 27, 1990 





398 SunView Programmer’s Guide 



V 

static 
start_dc ( ) 

{ 

int pipeto[2], pipefrom[2]; 

int c, numfds; 

if (pipe(pipeto) < 0 | | pipe(pipefrom) < 0) { 
perror ( "detool " ) ; 
exit ( 1) ; 



switch (childpid = fork()) { 
case -1: 



perror ( " detool " ) ; 
exit ( 1) ; 

case 0: /* this is the child process */ 

/* 

* use dup2 to set the child's stdin and stdout to the 

* pipes 
*/ 

(void)dup2(pipeto[0] , 0); 

(void)dup2 (pipef rom[l] , 1); 

/* 

* close all other fds (except stderr) since the child 

* process doesn't know about or need them 
*/ 

numfds = getdtablesize( ) ; 
for (c = 3; c < numfds; C++) 

(void)close(c) ; 

/* exec the child process */ 

( void) execl ( "/usr/bin/dc" , "dc", 0); 

perror ( "detool (child)"); /* shouldn't get here */ 

exit(l) ; 

default: /* this is the parent */ 

(void) close (pipeto[0] ) ; 

(void) close (pipef rom[ 1 ] ) ; 

tochild = pipeto[l]; 

fptochild = fdopen ( tochild, "w"); 

fromchild = pipefrom[0]; 

fp_fromchild = fdopen ( fromchild, "r"); 

/* 

* the pipe to dc must be unbuffered or dc will not get 

* any data until 1024 characters have been sent 
*/ 

setbuf (fp_tochild, NULL),-/ 
break ; 



} 



} 

/* 

* notify proc called whenever there is 

* from the child process; in this case 

* so we display it 
*/ 

static Notify_value 

pipereader ( frame, fd) 

Frame frame; 

int fd; 



char buf [512] ; 



data to read on 
it is an answer 



the pipe 
from dc, 
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(void) f gets (buf , 512, fp_f romchild) ; 

buf [ strlen (buf ) - 1] = ' ' ;/* remove newline */ 

panelset (display_item, PANEL_LABEL_STRING , buf, 0); 

displaybuf [0 ] = ' ' ; 

return (NOTIFY_DONE) ; 

I 

/* 

* notify proc called if the child dies 
*/ 

static Notify_value 

dead_child ( frame, pid, status, rusage) 

Frame frame; 

int pid; 

union wait *status; 

struct rusage *rusage; 

{ 

panel_set (display_item, PANEL_LABEL_STRING, "Child died!", 0); 
dead = 1 ; 

/* 

* tell the notifier to stop reading the pipe (since it is 

* invalid now) 

V 

(void) notify_set_input_f unc ( frame, NOTIFY_FUNC_NULL, 

f romchild) ; 

(void) close (tochild) ; 

(void)close(fromchild) ; 
return (NOTIFY_DONE) ; 

} 

/* send a character over the pipe to dc */ 
static 

send_to_dc(c) 

char c; 

( 

if (dead) 

panel_set (display_item, 

PANEL_LABEL_STRING , "Child is dead!", 

0 ) ; 

else 

( void) putc (c , fp_tochild) ; 

} 
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A.8. typein This program shows how to replace the functionality of the Graphics Tool and 

gfxsw package previously available under SunWindows. typein provides a tty 
emulator for interaction with the user and a canvas to draw on. To demonstrate 
it, a simple application is included which allows the user to input coordinates in 
the tty emulator and then draws the vectors in the canvas. 

typein uses a tty subwindow and a canvas. Normally, the tty subwindow is used 
to allow a child process to run in a window; in this case, we would like the same 
process to write in that window. To accomplish this, we tell the tty subwindow 
not to fork a child process with the TTY_ARGV_DO_NOT_FORK value for 
TTY_ARGV. typein uses dup2(2) to set its stdin and stdout to the TTY_FD. 
When the user types something in the tty subwindow, typein' s read_input ( ) 
routine is called. 

NOTE When using this mechanism, be careful of the following problems. First, you 

must use the Notifier (unlike the old gfxsw). Second, if you use the standard I/O 
package, be sure to either use f f lush carefully or to remove all buffering with 
setbuf because the package will think you are sending data to a file and not to 
a tty. Finally, be sure you never block on a read because the program will hang 
(either use non-blocking I/O or only read one line at a time). 
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#ifndef lint 

static char sccsidf] = "@( #) typein . c 1.5 87/01/07 Copyr 1986 Sun Micro"; 
#endif 



/***********************************************************y 
/* */ 

/* typein. c */ 

/* */ 

y***********************************************************^/ 

/***********************************************************^r 

/* V 

/* This program provides the user with a tty emulator */ 

/* for interaction and a canvas to draw on. The user */ 

/* has the ability to input coordinates in the tty */ 

/* emulator which then draws the vectors in the canvas. */ 

/* The user can also close, move, resize, hide, redisplay, */ 
/* or quit the window. */ 

/* */ 

y'***********************************************************^/ 



#include <stdio.h> 

#include <suntool/sunview. h> 
#include <suntool/canvas . h> 
#include <suntool/tty . h> 
#include <ctype.h> 
static Frame frame; 

static Canvas canvas; 

static Tty tty; 

static Pixwin *pw; 
static Notify_client 
#def ine STDIN_FD 
#def ine STDOUT_FD 
#def ine BUFSIZE 



my_client ; 
0 
1 

1000 



main(argc, argv) 
int argc; 
char **argv; 

{ 

static Notify_value read_input ( ) ; 
int tty_fd; 

frame = window_create(NULL, FRAME, 

FRAMEARGS, argc, argv, 

WIN_ERROR_MSG, "Cannot create frame", 

FRAME_LABEL, "typein", 

0 ); 

tty = windowcreate ( frame, TTY, 

WIN_PERCENT_HEIGHT, 50, 

TTY_ARGV, TTY_ARGV_DO_NOT_FORK, 

0 ); 

tty_fd = (int)window_get ( tty, TTY_TTY_FD) ; 

dup2 ( tty_fd, STDOUT_FD) ; 

dup2 ( tty_fd, STDIN_FD) ; 

canvas = window_create( frame, CANVAS, 

0 ); 

pw = canvas_pixwin (canvas ) ; 

/* 

* Set up a notify proc so that whenever there is input to read on 

* stdin (fd 0), we are called to read it. 




sun 

microsystems 



Revision A, of March 27, 1990 




402 SunView Programmer’s Guide 



1 

/* 

* 

* 

* 

* 



* Notifier needs a unique handle: give it the address of tty. 

V 

my_client = (Not ify_client ) &tty; 

notifysetinput func (myclient , read_input, STDIN_FD) ; 
printf ( "Enter first coordinate: nx? "); 
window_main_loop( frame) ; 
exit ( 0) ; 



This section implements a simple application which writes prompts to 
stdin and reads coordinates from stdout, drawing vectors with the 
supplied coordinates. It uses a state machine to keep track of what 
number to read next. 



V 

#def ine GET_X_1 0 
# define GET_Y_1 1 
#def ine GET_X_2 2 
#def ine GET Y 2 3 



int state = GET_X_1; 
int xl, yl, x2, y2; 

/* ARGSUSED */ 
static Notify_value 
readinput (client , in_fd) 
Notify_client client; 
int in_fd; 

{ 



char buf [BUFSIZE] ; 
char *ptr, *gets(); 
ptr = gets (buf); /* 



/* unused since this must be from ttysw */ 
/* unused since this is stdin */ 



read one line per call so that we 
don't ever block */ 

/* does this matter any more?? */ 



/* handle end of file */ 
if (ptr==NULL) { 

/* Note: could have been a read error */ 
window_set( frame, FRAME_NO_CONFI RM , TRUE, 0); 
window_done (tty ) ; 

] else { 



switch (state) { 
case GET_X_1 : 

if (sscanf(buf, "%d", &xl) ! = 1) { 

printf (" Illegal value! nx? "); 
ff lush(stdout) ; 

} else { 

printf ("y? "); 
ff lush(stdout) ; 
state++ ; 



} 

break; 



case GET_Y_1 : 

if (sscanf(buf, "%d", &yl) != 1) { 

printf (" Illegal value! ny? "); 
f f lush(stdout) ; 

} else { 

pr intf (" Enter second coordinate: nx? "); 
ff lush(stdout) ; 
state++ ; 

} 

break ; 
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case GET_X_2 : 

if (sscanf(buf, "%d", &x2) ! = 1) { 

printf (" Illegal value! nx? "); 
ff lush(stdout) ; 

} else { 

printf ( "y? " ) ; 
f flush (stdout) ; 
state++; 

} 

break ; 

case GET_Y_2 : 

if (sscanf(buf, "%d", &y2) != 1) { 

printf (" Illegal value! ny? " ) ; 
ff lush(stdout) ; 

} else { 

printf ( "Vector from (%d, %d) to (%d, %d) n", 
xl, yl, x2 , y2); 

pw_vector (pw, xl, yl, x2, y2 , PIX_SET, 1); 
printf (" nEnter first coordinate: nx? "); 
ff lush (stdout) ; 
state = GET_X_1 ; 

} 

break ; 

} 



} 

return (NOTIFY DONE); 
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A.9. Programs that 
Manipulate Color 



color edit 



The following two programs work with color. You can run them on a mono- 
chrome workstation to no ill-effect, but you won’t see much of interest. 

The techniques employed by these two programs are explained in the Color sec- 
tion of Chapter 7, Imaging Facilities: Pixwins. 

When using these programs, try invoking them with different colors using the 
frame’s command line arguments. Also, run showcolor (listed in the pixwin 
chapter) to see how the screen’s colormap changes as different color programs 
are run simultaneously. 

The first program, coloredit, puts up sliders that let the user modify its colors. 
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#ifndef lint 

static char sccsid[] = "@( #) coloredit . c 1.4 86/09/15 Copyr 1986 Sun Micro"; 
#endif 

^/***************************************************************************^y 

/***************************************************************************^z 

/* V 

/* coloredit. c */ 

/* */ 

^***************************************************************************^/ 
y'***************************************************************************^ 

/* V 

/* This program displays four sliders which will allow the user to modify */ 
/* the colors of the canvas directly below the sliders. The user has the */ 
/* ability to cycle through various colors on the canvas. */ 

/* */ 

y'***************************************************************************^/ 

#include <suntool/sunview . h> 

#include <suntool/panel . h> 

#include <suntool/canvas . h> 

#def ine MYFRAME 0 

#def ine MYPANEL 1 

ttdefine MYCANVAS 2 

/* colormap sizes for the three windows. Canvas is still the biggest */ 
mycms_sizes [3] = { 

2, 2, 4 

}; 



#def ine MYCMS_SIZE 4 


/* color arrays 


; initialize them with the canvas coli 


unsigned char 


red [ MY CMS_S I Z E ] = {0, 0, 255, 255}; 


unsigned char 


green [MYCMS_SIZE] = {0, 255, 0, 192] 


unsigned char 


blue [MYCMS_SIZE] = {255, 0, 0, 192}; 


static void 


getcms ( ) ; 


static void 


setcms ( ) ; 


static void 


cycle ( ) ; 


static void 


editcms ( ) ; 


static void 


set_color ( ) ; 


static void 


change value ( ) ; 


Panel item 


text item; 


Panel item 


color item; 


Panel item 


red item, green item, blue item; 


Pixwin 


*pixwins [3] ; 


Pixwin 


*pw ; 


main(argc, argv) 


int 


argc; 


char 

( 

Frame 


**argv; 


base frame; 


Panel 


panel ; 


Canvas 


canvas; 


Attr avlist sliderdef aults ; 


/* the 


cmsname is copied, so this array can ! 


char 


cmsname [ CMS_NAMESIZE] ; 


int 


counter; 


int 


xposition ; 


char 


buf [40] ; 



base_frame = window_create (NULL, FRAME, 
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FRAME_LABEL , "coloredit", 

FRAME_ARGS, argc, argv, 

0); 

/* set up the panel */ 

panel = window_create (base_frame, PANEL, 

0); 

/* create a reusable attribute list for my slider attributes */ 
sliderdef aults = attr_create_list ( 

P ANEL_SHOW_I TEM , TRUE, 

P ANEL_MI N_VALUE , 0, 

PANEL_MAX_VALUE, 255, 

PANEL_SLIDER_WIDTH, 512, 

P ANEL_SHOW_RANGE , TRUE, 

PANEL_SHOW_VALUE, TRUE, 

P ANEL_NOT I FY_LEVEL , PANEL_ALL, 

0); 

panel_create_i tern ( panel , PANEL_CYCLE , 

PANEL_LABEL_STRING , "Edit colormap:", 

PANEL_VALUE , MYCANVAS, 

PANEL_CHOICE_STRINGS, "Frame", "Panel", "Canvas", 0, 
PANEL_NOTIFY_PROC, editcms, 

0 ); 

text_item = panel_create_item (panel , PANEL_TEXT, 

PANEL_VALUE_DISPLAY_LENGTH , CMS_NAMESI ZE , 

P ANEL_VALUE_STORED_LENGTH , CMS_NAMES I ZE , 

0) ; 

color_item = panel_create_item(panel , PANEL_SLIDER, 

ATTR_LIST, sliderdef aults , 

PANEL_LABEL_STRING , " color : " , 

PANEL_NOTIFY_PROC , set_color, 

0); 

red item = panel_create_item ( panel , PANEL_SLIDER, 

ATTR_LIST, sliderdef aults , 

PANEL_LABEL_STRING, " red:", 

PANEL_NOTIFY_PROC , change_value, 

0); 

green_item = panel_create_item ( panel , PANEL_SLIDER, 

ATTR_LIST, sliderdef aults , 

PANEL_LABEL_STRING, "green : " , 
PANEL_NOTIFY_PROC, changevalue , 

0 ) ; 

blue_item = panel_create_item (panel , PANEL_SLIDER, 

ATTR_LIST , sliderdef aults , 

PANEL_LABEL_STRING , " blue:", 
PANEL_NOTIFY_PROC, change_value , 

0); 

panel_create__item ( panel , PANEL_BUTTON , 

PANEL_LABEL_IMAGE , 

panel_button_image ( panel , "Cycle colormap", 12, NULL), 
PANEL_NOTIFY_PROC, cycle, 

0); 

windowf it (panel ) ; 
window_fit_width (base frame) ; 

/* free the slider attribute list */ 
free(sliderdefaults) ; 

/* set up the canvas */ 

canvas = window_create(base_f rame, CANVAS, 0); 
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/* get pixwins */ 

pixwins [MYFRAME] = (Pixwin *) window_get (base_f rame , WIN_PIX'WIN) ; 
pixwins [MYPANEL] = (Pixwin *) window_get (panel , WIN_PIXWIN) ; 
pw = pixwins [MYCANVAS ] = (Pixwin *) canvas_pixwin ( canvas ) ; 

/* set up the canvas' colormap */ 
sprintf (cmsname, " coloredit%D" , getpid()); 
pw_setcmsname (pw, cmsname); 

pw_putcolormap(pw, 0, mycms_s izes [MYCANVAS ] , red, green, blue); 

/* draw in the canvas */ 

/* don't draw color 0 -- it is the background */ 
for (counter = 1; counter < mycms_sizes [MYCANVAS] ; counter++) { 
xposition = counter * 100; 
pw_rop(pw, xposition, 50, 50, 50, 

PIXSRC | PIX_C0L0R ( counter ) , NULL, 0, 0); 
sprintf (buf, "%d", counter); 

pw_text(pw, xposition + 5, 70, PIX_SRC ~ PIX_DST, 0, buf); 

1 

pw_text(pw, 100, 150, 

PIX_SRC | PIX_COLOR(mycms_sizes [MYCANVAS] - 1), 0, 

"This is written in the foreground color"); 

/* initialize to edit the first canvas color */ 
editcms (NULL, MYCANVAS, NULL); 
window_main_loop (base_f rame) ; 
exit ( 0 ) ; 



static int cur_cms = -1; 

/* ARGSUSED */ 



static void 

editcms ( item, value, event) 

Panel_item item; 

unsigned int value; 

Event *event; 



int planes; 

struct colormapseg cms ; 
char cmsname [CMS_NAMESIZE] ; 

if (value == curcms) 
return ; 

curcms = value; 

/* get the new cmsname */ 

pw_getcmsname (pixwins [ cur_cms ] , cmsname ) ; 
panel_set_value( textitem, cmsname) ; 
pw = pixwins [curcms] ; 

/* get the new colormap */ 

/* 

* first have to get its size there is NO DOCUMENTED procedure to do 

* this. 

*/ 



pw_getcmsdata (pw, &cms, &planes); 

pw_getcolormap(pw, 0, cms. cms size, red, green, blue); 
panelset ( color_item, 

PANEL_VALUE , 0, 

PANEL_MAX_VALUE, cms.cms_size - 1, 

0 ); 

/* call the proc to set the colors */ 
set_color (NULL, 0, NULL) ; 

] 

int cur_color; 
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/* ARGSUSED */ 
static void 

set_color ( item, color, event) 

Panelitem item; 

unsigned int color; 

struct inputevent *event; 

{ 

panel_set_value( red_item, red [color] ) ; 
panel_set_value(green_item, green [color] ) ; 
panel_set_value(blue_item, blue [color] ) ; 
curcolor = (unsigned char) color; 

] 

/* ARGSUSED */ 
static void 

changevalue ( item, value, event) 

Panel_item item; 

int value; 

struct inputevent *event; 



if (item == red_item) 

red [cur_color] = (unsigned char) value; 
else if (item == green_item) 

green [cur_color] = (unsigned char) value; 

else 



blue[cur_color] = (unsigned char) value; 

/* 

* pw_putcolormap expects arrays of colors, but this only sets one 

* color 
*/ 

pw_putcolormap (pw, cur_color, 1, 

&red[cur_color] , &green [cur_color ] , &blue[cur_color] ) ; 

1 

/* ARGSUSED */ 
static void 
cycle (item, event) 

Panel_item item; 

Event * event; 

{ 

pw_cyclecolormap (pw, 1, 0, mycms_s izes [ cur_cms ] ) ; 

} 
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animatecolor This program demonstrates smooth animation via the technique of software 

double-buffering. Two colormaps for the canvas are set up so that while one is 
being written two, the other is being displayed. This allows smoother animation. 

The routines that set up the colormaps and swap them, doublebuff _init ( ) 
and doublebuf f _swap ( ) , are general enough to be used in other programs 
that alternate two colormaps. You need only set up a similar colorstuf f 
structure to use these routines in another program. 

The logic involved in creating the colormaps is complex. The colormaps created 
for animatecolor are given in the table Sample Colormap to Isolate Planes in the 
pixwin chapter. 
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^z***************************************************************^/ 

#ifndef lint 

static char sccsidf] = "(3(#)animatecolor.c 1.4 88/03/09 Copyr 1986 Sun Micro"; 



#endif 

^Z***************************************************************^z 

/* */ 

/* animatecolor . c */ 

/* */ 

/*******************★********************•******★************★***/ 
y/***************************************************************/ 

/* V 

/* This program has three colored squares ricochetting across */ 
/* a colored canvas. One of the squares is recochetting at */ 

/* a much faster rate then the other two squares . */ 

/* V 



^***************************************************************/ 
#include <suntool/sunview . h> 

#include <suntool/canvas . h> 

^***************************************************************^z 
/* You set MYCOLORS & MYNBITS according to how many colors */ 

/* you are using; rest is just boilerplate, more or less; */ 

/* it you define your colors. */ 

^***************************************************************^ 
/* 

* define the colors I want in the canvas; max 16, must be a 

* power of 2 
*/ 

#def ine MYCOLORS 4 

/* 

* define the number of bits my colors take up -- MYCOLORS log 2; 

* maximum for animation to be possible is half screen's bits per 

* pixel -- 4 bits on current Sun color displays. 

V 

#def ine MYNBITS 2 



/* 

* to "hide" one set of planes while displaying another takes 

* large cms -- the square of the number of colors 
*/ 



#def ine MYCMS_SIZE (MYCOLORS * MYCOLORS) 

/* 

* when you write out a color pixel, you must write the color 

* the appropriate planes. This macro writes it in both sets 



V 



( (i) | ((i) << colorstuf f . colorbits ) 



#define usecolor(i) 
struct colorstuff { 

/* desired colors */ 

unsigned char redcolors [MYCOLORS] ; 

unsigned char greencolors [MYCOLORS] ; 
unsigned char bluecolors [MYCOLORS] ; 

/* number of bits the desired colors take up */ 
int colorbits; 

/* colormap segment size */ 
int cms_size; 

/* 2 colormaps to support it */ 
unsigned char red [ 2 ] [MYCMS_SIZE] ; 

unsigned char green [2 ] [MYCMS_SIZE] ; 

unsigned char blue [2] [MYCMS_SIZE] ; 

/* 2 masks to support it */ 



a 



in 



) 
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int enable_0_mask ; 

int enable_l_mask; 

/* current colormap -- 0 or 1 */ 
int cur buff; 

/* plane mask to control which planes are written to */ 
int planemask; 

]; 

struct colorstuff colorstuff = [ 

/* desired red colors */ 

{ 0 , 0 , 255 , 255 }, 

/* desired green colors */ 

{ 0 , 255 , 0 , 192 ], 

/* desired blue colors */ 

{ 255 , 0 , 0 , 192 ], 

/* number of planes these colors take up */ 

MYNBITS, 



/* colormap segment size */ 

MYCMS_SIZE, 

/* rest filled in later */ 

]; 



static void resize_proc ( ) ; 

/* stuff needed to do random numbers */ 

extern void srandom( ) ; 

extern int getpid(); 

extern long random(); 

extern char *sprintf(); 

static Notify_value my_f rame_interposer ( ) ; 

static Notify_value my_draw(); 

static Pixwin *pw; 

static int times_drawn; 

static int Xmax, Ymax; 

main(argc, argv) 

int argc; 



{ 



uhai * *argv; 

Frame base_frame; 

Canvas canvas; 

base_frame = window_create( (Window) NULL, FRAME, 

FRAMELABEL, "animatecolor " , 
FRAME_ARGS, argc, argv, 

0 ); 

canvas = window_create (base_f rame, CANVAS, 

CANVAS_RETAINED, TRUE, 
CANVAS_RESIZE_PROC , resizeproc, 
0 ); 

pw = (Pixwin *) canvaspixwin (canvas) ; 

/* set up the canvas' colormap */ 
doublebuf f_init ( scolorstuf f ) ; 

/* run the drawing routine as often as possible */ 
(void) notify_set_itimer_func(base_frame, my_draw, 



ITIMER_REAL, 
&NOTIFY_POLLING_ITIMER, 
((struct itimerval *) 0)); 
/* initialize the random function */ 
srandom (getpid( ) ) ; 
window_main_loop (base_f rame ) ; 
exit ( 0 ) ; 
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/* ARGSUSED */ 

static Notify_value 



my_draw( client, itimer_type) 

Notify_client client; 
int itimer_type; 

{ 

/* 

* draw the squares, then swap the colormap to animate them 

V 

#def ine SQUARESIZE 50 

#def ine MAX_VEL (SQUARESIZE / 5) 

/* number of squares to animate */ 

#def ine NUMBER (MYCOLORS - 1) 

static int posx [NUMBER] , posy [NUMBER] ; 

static int vx [ NUMBER ] , vy[NUMBER]; 

static int prevposx [ NUMBER ] , prevposy [NUMBER] ; 

int i; 

/* set the plane mask to be that which we are not viewing */ 
pw_putattributes (pw, (colorstuf f . cur_buf f == 1) ? 

& (colorstuf f . enable_l_mask) : & (colorstuff . enable_0_mask) ) ; 
/* write to invisible planes */ 
for (i = 0; i < NUMBER; i++) { 

if ( ! times_drawn ) [ 

/* first time drawing */ 
posx[i] = (i + 1) * 100; 
posy[i] = 50; 

vx [ i ] = r(-MAX_VEL, MAX_VEL) ; 
vy [ i ] = r(-MAX_VEL, MAX_VEL) ; 

} 

if (abs(vx[i]) > MAX_VEL) { 

printf ( "Weird value (%d) for vx[%d] n", vx[i], i); 
vx[i] = r(-MAX_VEL, MAX_VEL) ; 

] 

posx[i] = posx[i] + vx[i]; 

if (posx[i] < 0) { 

/* Bounce off the left wall */ 
posx[i] = 0; 
vx [ i ] = - vx [ i] ; 

} else if (posx[i] > Xmax - SQUARESIZE) { 

/* Bounce off the right wall */ 

vx [ i ] = - vx [ i ] ; 

posx[i] = posx[i] + vx[i]; 

] 

posy [ i] = posy [ i] + vy[i]; 

if (posy [ i ] > Ymax - SQUARESIZE) [ 

/* Bounce off the top */ 
posy[i] = Ymax - SQUARESIZE; 
vy [i] = -vy [i] ; 

} else if (posy[i] < 0) { 

/* Bounce off the bottom */ 
posy[i] = 0; 
vy [i] = -vy [ i] ; 

] 

/* draw the square you can't see */ 

pw_rop(pw, posx[i], posy[i], SQUARESIZE, SQUARESIZE, 

PIX_SRC | PIX_COLOR ( usecolor ( i + 1)), NULL, 0, 0); 

} 

/* 
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* swap the colormaps, and hey presto! should appear smoothly 

V 

doublebuf f_swap ( &colorstuf f ) ; 
times_drawn++ ; 

/* set the plane mask to be that which we are not viewing */ 
pwputattributes (pw, ( colors tuff . cur_buf f == 1) ? 

& (color stuff . enable_l_mask ) : & ( color stuff . enable_0_mask) ) ; 
/* erase now invisible planes */ 
for (i = 0; i < NUMBER; i++) { 
if (times_drawn >1) { 

/* squares have been drawn before */ 

/* erase in the one you can't see */ 
pw_rop(pw, prevposxfi], prevposyfi], 

SQUARESIZE, SQUARESIZE, PIX_CLR, NULL, 0, 0); 

1 

/* remember so can erase later */ 
prevposxfi] = posx[i]; 
prevposyfi] = posyfi]; 

1 

/* 

* set the plane mask to be that which we are viewing, in 

* case screen has to be repaired between now an when we are 

* called again. 

*/ 

pw_putattributes (pw, ( colorstuf f . cur_buf f == 1) ? 

& (colorstuf f . enable_0_mask) : &( colorstuf f . enable_l_mask) ) ; 

] 

/* random number calculator */ 
int 

r (minr, maxr) 



int 


minr, maxr 


int 


i; 



i = random() % (maxr - minr + 1); 
if (i < 0) 

return (i + maxr + 1) ; 

else 

return (i + minr); 

1 

/* ARGSUNUSED */ 
static void 

resizeproc ( canvas , width, height) 

t 

timesdrawn = 0; 

/* remember, pixels start at 0, not 1, in the pixwin */ 

Xmax = width - 1; 

Ymax = height - 1; 

1 

/* 

* Do double buffering by changing the write enable planes and 

* the color maps. The application draws into a buffer which is 

* not visible and when the buffers are swapped the invisible one 

* become visible and the other become invis. 

* 

* Start out drawing into buffer 1 which is the low-order buffer; 

* ie. the low-order planes. Things would not work if this is not 

* done because the devices start out be drawing with color 1 

* which will only hit the low-order planes. 
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* Init double buffering: Allocate color maps for both buffers. Fill 

* in color maps . 

V 

doublebuf f_init ( colorstuf f ) 

struct colorstuff *colorstuff; 

i 

/* 

* user has defined desired colors. Set them up in the two 



* colormap 


segments 


V 




int 


index_l ; 


int 


index_2 ; 


int 


i ; 


char 


cmsname [CMS_NAMESIZE] 



/* name colormap something unique */ 
sprintf ( cmsname, "animatecolor%D" , getpid()); 
pw_setcmsname ( pw, cmsname); 

/* 

* for each index in each color table, figure out how it maps 

* into the original color table. 

V 

for (i = 0; i < colorstuf f- >cms_s ize; i++) { 

/* 

* first colormap will show color X whenever low order 

* bits of color index are X 
*/ 

index_l = i & ((1 << colorstuf f ->colorbits) - 1); 

/* 

* second colormap will show color X whenever high order 

* bits of color index are X 

*/ 

index_2 = i >> colorstuf f- >colorbits ; 

colorstuf f - >red [ 0 ][ i] = colorstuf f->redcolors [ index_l] ; 
colorstuf f->green [ 0 ][ i ] = colorstuf f- >greencolors [ index_l ] ; 
colorstuf f->blue [0] fi] = colorstuf f - >bluecolors [index_l] ; 
colorstuf f - >red [ 1 ][ i] = colorstuf f- >redcolors [ index_2 ] ; 
colorstuf f->green [ 1] [ i] = colorstuff - >greencolors [index_2 ] ; 
colorstuf f - >blue [ 1 ][ i ] = colorstuf f- >bluecolors [ index 2 ] ; 

] 

colorstuf f ->enable_l_mask = ((1 << colorstuf f ->colorbits) - 1) 

<< colorstuf f->colorbits ; 

colorstuf f ->enable _0_mask = ((1 << colorstuf f ->colorbits) - 1); 

/* 

* doublebuf f swap sets up the colormap. We want the drawing 

* to start off drawing into the 1st buffer, so set the 

* current buffer to 1 so that when doublebuf f_swap is called 

* it will set up the first ([0] ) colormap. 

*/ 

colorstuff ->cur_buff == 1; 
doublebuf f_swap ( colorstuf f ) ; 

] 

/* 

* Routine to swap buffers by loading a color map that will show 

* the contents of the buffer that was not visible. Also, set the 

* write enable plane so that future writes will only effect the 

* planes which are not visible. 

V 

l 
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doublebuff_swap (colorstuf f ) 

struct colorstuff *colorstuff; 



t 



if (colorstuf f->cur_buff == 0) { 

/* display first buffer while writing to 2nd */ 

/* 

* Careful! pw putcolormap ( ) wants an array or pointer 

* passed, but the colormap arrays are 2-d 
*/ 

pw_putcolormap(pw, 0, colorstuf f- >cms_s ize, 
colorstuf f- >red [0 ] , 
colorstuf f- >green [ 0 ] , 
colorstuf f->blue[0] ) ; 

/* set plane mask to write to second buffer */ 
colorstuf f ->plane_mask = colorstuf f- >enable_l_mask ; 
colorstuf f->cur_buff = 1; 

} else { 

/* display second buffer while writing to first */ 
pw_putcolormap (pw, 0, colorstuf f->cms_size, 
colorstuff->red[l] , 
colorstuf f- >green [ 1] , 
colors tuf f- >blue [ 1 ] ) ; 

/* set plane mask to write to first buffer */ 
colorstuf f ->plane_mask = colorstuf f ->enable_0_mask; 
colorstuf f ->cur_buf f = 0; 



} 
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A.10. Twogfx 

subwindow-based 
programs converted 
to use SunView 



bounce 



The following two programs are the Sun demo programs bouncedemo and 
spheresdemo converted from using gf xsw init ( ) to canvases in SunView. 

The code for the SunWindows-based programs is in 

/usr/share/src/sun/suntool so you can contrast that code with the 
SunView versions printed here. 

Techniques used to convert programs such as these to SunView 1 are described 
in Appendix C, Converting SunWindows Programs to SunView. 

The first program is bouncedemo converted to draw in a canvas and to call 
not if y_dispatch ( ) periodically. Like the original bouncedemo, it restarts 
drawing after any damage (if not retained) or resizing. 



#sun 

Xr microsystems 



Revision A, of March 27, 1990 





Appendix A — Example Programs ( bounce ) 417 



#ifndef lint 

static char sccsid[] = "(3( #) bounce . c 1.5 88/02/26 Copyr 1986 Sun Micro"; 



#endif 

/* V 

/* bounce. c */ 

/* */ 

/* */ 

/* This program bounces a ball across the canvas. The ball bounces */ 
/* continuously and then momentarily the canvas is cleared and the */ 

/* ball continues to bounce again. */ 

/* V 



/* Overview: Bouncing ball demo in window. */ 

/* Converted to use SunView by simulating the gfxsubwindow structure.*/ 

/* this replaces all includes */ 

#include <suntool/sunview . h> 
ttinclude <suntool/canvas.h> 

/* straight from the Canvas chapter */ 
static void repaint_proc ( ) ; 

static void resize_proc ( ) ; 

/* straight from the Notifier chapter */ 
static Notify_value my_notice_destroy ( ) ; 
extern Notif y_error notify_dispatch ( ) ; 
static int my_done; 

/* define my own gfxsubwindow struct */ 
struct gfxsubwindow [ 



int 


gfx_f lags ; 


#def ine GFX_RESTART 


0x01 


#def ine GFX_DAMAGED 


0x02 


int 


gfx reps; 


struct pixwin 


*gfx pixwin; 


struct rect 


gfx_rect ; 


] mygfx 


; 


struct gfxsubwindow * 


gfx = &mygfx; 


main(argc, argv) 


int 


argc ; 


char 

r 


**argv; 


l 

short 


x, y, vx, vy, z, ylastcount, ylast; 


short 


Xmax, Ymax, size; 



/* WIN_RECT attribute returns a pointer */ 

Rect *rect; 

/* have to handle this arg that gfxsw_init used to process */ 
int retained = 0; 

/* 

* replace this call if (gfx == (struct gfxsubwindow *)0) exit(l); 

* with . . . 

V 

Frame frame; 

Canvas canvas; 

Pixwin *pw; 

/* this arg was also dealt with by gfxsw_init */ 
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gfx->gfx_reps = 200000; 

frame = window_create (NULL, FRAME, 

FRAME_LABEL , " bounce " , 

FRAME_ARGC_PTR_ARGV , &argc, argv, 

WIN_ERROR_MSG, "Can't create frame", 

0 ); 

for (--argc, ++argv; *argv; argv++) { 

/* 

* handle the arguments that gf xswinit ( 0 , argv) used to do 

* for you 

V 

if ( strcmp ( *argv, " -r") == 0) 
retained = 1; 

if (strcmp( *argv, "-n") == 0) 
if (argc > 1) { 

(void) sscanf ( * (++argv) , "%hD", &gf x->gfx_reps ) ; 

argc++ ; 

} 

1 

canvas = window_create( frame, CANVAS, 

CANVAS_RETAINED , retained, 

CANVAS_RESIZE_PROC, resize_proc, 

CANVAS_FAST_MONO , TRUE, 

WIN_ERROR_MSG, "Can't create canvas", 

0); 

/* only need to define a repaint proc if not retained */ 
if (! retained) { 

window_set ( canvas , 

CANVAS_REPAINT_PROC , repaint_proc , 

0 ); 

) 

pw = canvas_pixwin ( canvas ) ; 

gfx- >gf x_pixwin = canvas_pixwin (canvas ) ; 

/* Interpose my proc so I know that the tool is going away. */ 

(void) notify_interpose_destroy_func ( frame, my_notice_destroy ) ; 

/* 

* Note: instead of window_main_loop, just show the frame. The 

* drawing loop is in control, not the notifier. 

*/ 

window_set( frame, WIN_SH0W, TRUE, 0); 

Restart : 

rect = (Rect *) window_get ( canvas , WIN_RECT) ; 

Xmax = rect_right(rect) ; 

Ymax = rect_bottom( rect ) ; 
if (Xmax < Ymax) 

size = Xmax / 29 + 1; 

else 

size = Ymax / 29 + 1; 

/* 

* the following were always 0 in a gfx subwindow (bouncedemo 

* is confused on this point 
*/ 

x = 0 ; 

y - 0; 

vx = 4 ; 
vy = 0; 
ylast = 0 ; 

v ) 
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ylastcount = 0; 

pw_wri tebackground (pw, 0, 0, rect->r_width, rect->r_height , 
PIX_SRC) ; 

/* 

* Call notify_dispatch( ) to dispatch events to the frame 

* regularly. This will call my resize and repaint procs and 

* interposed notif y_destroy_f unc if necessary. The latter will 

* set my_done to TRUE if it's time to finish. 

V 

while (gfx->gfx_reps ) { 

(void) notify_dispatch( ) ; 
if (mydone) 

break; 



/* 

* this program is not concerned with damage, because either 

* the canvas repairs the damage (if retained) or it just 

* restarts, which is handled by GFX_RESTART 
*/ 

/* 

* if (gfx->gfx_flags&GFX_DAMAGED) gfxsw_handlesigwinch ( gf x) ; 

V 

if ( gfx- >gf x_f lags & GFX_RESTART) { 

gfx- >gf x_f lags &= ~GFX_REST ART ; 
goto Restart; 

1 

if (y == ylast) { 

if (ylastcount++ > 5) 
goto Reset; 

} else { 

ylast = y; 
ylastcount = 0; 

} 

pw_wri tebackground (pw, x, y, size, size, 

PIX_N0T ( PIX_DST ) ) ; 

x = x + vx ; 

if (x > (Xmax - size)) { 

/* 

* Bounce off the right edge 

V 

x = 2 * (Xmax - size) - x; 
vx = -vx; 

} else if (x < 0) { 

/* 

* bounce off the left edge 
*/ 



x = -x; 
vx = -vx; 

1 

vy = vy + 1 ; 



y = y 

if (y 






+ vy; 

>= ( Ymax - size) ) { 

/* 

* bounce off the bottom edge 

V 

y = Ymax - size; 
if (vy < size) 

vy = 1 - vy; 

else 
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vy = vy / size - vy; 
if (vy == 0) 

goto Reset; 

} 

for (z = 0; z <= 1000; z++); 
continue; 

if ( - -gfx->gfx_reps <= 0) 
break ; 

X — 0 ; 
y = 0; 
vx = 4 ; 
vy = 0; 
ylast = 0; 
ylastcount = 0; 



static void 

repaintproc ( /* Ignore args */ ) 

t 

/* if repainting is required, just restart */ 
gfx->gfx_flags | = GFX_RESTART; 

} 

static void 

resize_proc( /* Ignore args */ ) 

{ 

gfx* >gf x_f lags |= GFX_RESTART; 

] 

/* this is straight from the Notifier chapter */ 
static Notify_value 

my_not icedestroy ( frame , status) 

Frame frame; 

Destroy_status status; 

{ 

if (status ! = DESTROY_CHECK ING ) { 

/* set my flag so that I terminate my loop soon */ 
my_done = 1 ; 

/* Stop the notifier if blocked on read or select */ 
(void) notify_stop ( ) ; 

1 

/* Let frame get destroy event */ 

return ( notif y_next_destroy_f unc ( frame, status)); 
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spheres This is an example of a program that has been converted to use 

window_main_loop ( ) . It displays a fixed-sized image in a canvas that has 
scrollbars. It continues drawing its image when its window is damaged or 
resized. However, it stops drawing when it is iconic. 

You will have to create your own icon for this called spheres . icon. 
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#ifndef lint 

static char sees id [] = "(§( #) spheres . c 1.4 88/02/05 Copyr 1986 Sun Micro"; 
#endif 



^/*********************************************************************^/ 
/* */ 

/* spheres . c */ 

/* */ 

y'*****-****************************************************************/ 
y'*********************************************************************^ 

/* V 

/* This program displays a fixed-sized image in a canvas that has */ 

/* scroll bars. The image that this program continues to display */ 

/* are overlaping colored spheres. This program displays spheres */ 

/* of different sizes. The user also has the ability to close, */ 

/* move, resize, hide, redisplay, or quit the window. If the window */ 
/* is damaged or resized, the program continues to redraw the image. */ 
/* Yet, if the user closes the window the program discontinues to */ 

/* draw the image, but instead displays the iconic representation of */ 
/* the application. */ 

/* V 

/★★★a*****************************************************************/ 



/* 

* spheres -- draw a bunch of shaded spheres Algorithm was done 

* by Tom Duff, Lucasfilm Ltd., 1982 

* Revised to use SunView canvas instead of gfxsw. 



*/ 

#include <suntool/sunview . h> 

#include <suntool/canvas . h> 

#include <suntool/scrollbar . h> 

#include <sunwindow/cms_rainbow. h> 
static Notify_value my_f rame_interposer ( ) ; 
static Notify_value my_animation ( ) ; 
static void sphere(); 

static void demof lushbuf ( ) ; 

#define ITIMER_NULL ((struct itimerval *)0) 

/* 

* (NX, NY, NZ) is the light source vector -- length should be 

* 100 

V 



#define NX 48 
#define NY -36 
#define NZ 80 

#def ine BUF_BITWIDTH 16 
static struct pixrect *mpr; 

width; 



static int 
static int 
static int 
static Frame 
static Canvas 
static int 
static Pixwin 
static short 



height ; 
counter; 
frame ; 
canvas ; 
emssize; 

*pw; 

spheres_image [256 ] 



#include " spheres . icon " 

}; 



mpr_static ( spheres_pixrect , 64, 64 
main(argc, argv) 



= ( 



1, spheres_image) ; 
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int argc; 

char **argv; 

char **args; 

int usefullgray = 0; 

Icon icon; 

icon = icon_create ( ICONIMAGE, &spheres_pixrect , 0); 
frame = window_create(NULL, FRAME, 

FRAME_LABEL , "spheres " , 

FRAME_ICON, icon, 

FRAME_ARGC_PTR_ARGV, &argc, argv, 

0); 

canvas = window_create( frame, CANVAS, 

CANVAS_AUTO_EXPAND , 0 , 

CANVAS_AUTO_SHRINK, 0, 

CANVAS_AUTO_CLEAR, 0, 

/* 

* Set SCROLL_LINE_HEIGHT to 1 so that clicking LEFT or RIGHT 

* in the scroll buttons scrolls the canvas by one pixel. 

*/ 

WIN_VERTICAL_SCROLLBAR, scrollbar_create ( SCROLL_LINE_HEIGHT , 

0), 

WIN_HORIZONTAL_SCROLLBAR , scrollbar_create ( SCROLL_LINE_HEIGHT , 

0 ), 



0 ); 

for (args = argv; *args; args++) [ 
if (strcmp(*args, "-g") == 0) 
usefullgray = 1; 



1 

/* Interpose in front of the frame's client event handler */ 
(void) notify_interpose_event_f unc ( frame , my_f rame_interposer , 

NOTIFY_SAFE) ; 

(void) notify_set_itimer_func( frame, my_animation , 



ITIMER_REAL, & NOT I FY_POLL I NG_I T I MER , ITIMER_NULL) ; 
width = (int) window_get (canvas , CANVAS_WIDTH) ; 
height = (int) window_get ( canvas , CANVAS_HEIGHT) ; 
pw = canvas_pixwin (canvas ) ; 

cmssize = (usefullgray) ? setupfullgraycolormap(pw) : 
setuprainbowcolormap (pw) ; 

mpr = mem_create(BUF_BITWIDTH, height, pw- >pw_pixrect->pr_depth) 
window_main_loop ( frame) ; 
exit ( 0 ) ; 



} 



static 


int 


radius 


static 


int 


xO ; 


static 


int 


yo ; 


static 


int 


color; 


static 


int 


x; 


static 


int 


y; 


static 


int 


maxy ; 


static 


int 


mark; 


static 


int 


xbuf ; 



/* ARGSUSED */ 



/* x center */ 
/* y center */ 



static Notify_value 

my_animation (client , itimer_type) 
Notify_client client; 
int itimer_type; 



{ 



1 / 



1 / 
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register i; 

if (x >= radius) { 

radius = r(0, min (width / 2, height / 2)); 
xO = r ( 0 , width) ; 
yO = r ( 0 , height) ; 

color = r(0, cmssize + counter++) % cmssize; 
x = -radius; 
xbuf = 0; 

/* 

* Don't use background colored sphere. 

V 

if (color == 0) 
color++ ; 

/* 

* Don't use tiny sphere. 

V 

if (radius < 8) 
radius = 8; 

1 

for (i = 0; i < 5; i++) { 
xbuf ++ ; 



maxy = sqroot ( radius * radius - x * x); 
pw_vector (pw, xO + x, yO - maxy, xO + x, yO + maxy, 
PIX_CLR , 0); 

for (y = -maxy; y <= maxy; y++ ) { 

mark = r(0, radius * 100) <= NX * x + NY * y 

+ NZ * sqroot ( radius * radius -x*x-y*y); 
if (mark) 

pr_put(mpr, xbuf, y + yO , color); 

} 

if (xbuf == (mpr- >pr_width - 1)) { 

demof lushbuf (mpr, PIX_SRC | PIX_DST, 

x + xO - mpr- >pr_width, pw) ; 

xbuf = 0; 
x++ ; 

return (NOTIFY_DONE) ; 

} 

x++ ; 

1 

if (x >= radius) 

demof lushbuf (mpr , PIXSRC | PIX_DST, x + xO - (xbuf + 2), 
pw) ; 

return (NOTIFY_DONE) ; 

1 

static void 

demof lushbuf (mpr , op, x, pixwin) 
struct pixrect *mpr; 
int op; 

int x; 

struct pixwin *pixwin; 

{ 

register u_char *sptr, *end; 

sptr = mprd8_addr (mpr_d (mpr ) , 0, 0, mpr- >pr_depth) ; 
end = mprd8_addr (mpr_d(mpr) , mpr->pr_width - 1, 

mpr->pr_height - 1, mpr->pr_depth) ; 

/* 

* Flush the mpr to the pixwin. 

V 
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pw_write (pixwin, x, 0, mpr->pr_width, mpr->pr_height , op, 
mpr , 0 , 0 ) ; 

/* 

* Clear mpr with 0's 
*/ 

while (sptr <= end) 

*sptr++ = 0; 

/* Let user interact with tool */ 
notify_dispatch( ) ; 

] 

static int 

setuprainbowcolormap ( pw) 

Pixwin *pw; 

{ 

register u_char red [CMS_RAINBOWSIZE] ; 
register u_char green [CMS_RAINBOWSIZE] ; 
register uchar blue [CMS_RAINBOWSIZE] ; 

/* 

* Initialize to rainbow cms . 

*/ 

pw_se terns name (pw, CMS_RAINBOW) ; 
cms_rainbowsetup ( red, green, blue); 

pw_putcolormap(pw, 0, CMS_RAINBOWSIZE, red, green, blue); 
return (CMS_RAINBOWSIZE) ; 

1 

static int 

setupfullgraycolormap (pw) 

Pixwin *pw ; 

{ 

#def ine CMS_FULLGRAYS I ZE 256 

#def ine CMS_FULLGRAY "fullgray" 

register u_char red [CMS_FULLGRAYSIZE] ; 
register u_char green [CMS_FULLGRAYSIZE] ; 
register u_char blue [CMS_FULLGRAYSIZE] ; 
register i; 

/* 

* Initialize to rainbow cms. 

*/ 

pw_set cms name (pw, CMS_FULLGRAY) ; 
for (i = 0; i < CMS_FULLGRAYSI ZE ; i++) { 
redfi] = green[i] = blue[i] = i; 

} 

pw_putcolormap(pw, 0, CMS_FULLGRAYSIZE, red, green, blue); 
return (CMS_FULLGRAYSIZE) ; 

] 

static Notify_value 

my_f rame_interposer ( frame, event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notif y_event_type type; 

{ 

int closed_initial , closed_current ; 

Notify_value value; 

/* Determine initial state of frame */ 

closed_initial = (int) window_get ( frame , FRAME_CLOSED) ; 

/* Let frame operate on the event */ 

value = notif y_next_event_f unc ( frame, event, arg, type); 

v ) 
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/* Determine current state of frame */ 

closed_current = (int) window_get (frame, FRAME_CLOSED) ; 

/* Change animation if states differ */ 
if (closed_init ial != closedcurrent ) { 
if ( closed_current ) [ 

/* Turn off animation because closed */ 

(void) notify_set_itimer_func( frame, my animation, 

ITIMER_REAL, ITIMER_NULL, ITIMER_NULL ) ; 

} else { 

/* Turn on animation because opened */ 

(void) notify_set_itimer_func( frame, myanimation , 

ITIMER_REAL, &NOTIFY_POLLING_I TIMER, 

ITIMERJNULL) ; 

] 

1 

return (value); 

1 

s ' 
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B.l. Program Names 



B.2. Frame Headers 



B.3. Menus 

Capitalization 




Sun User Interface Conventions 



The window programs released by Sun follow some standard user interface con- 
ventions. These conventions are described here so that, if you choose, you can 
design your interfaces with them in mind. 

Here are some guidelines for naming programs: 

□ A window-based version of an existing tty-based program has tool appended 
to the end of the existing program. For example mail tool is a window- 
based version of the tty-based program mail(l). 

□ A program without a tty version should not end with tool. Thus the icon edi- 
tor is called iconedit and not icontool. 

□ Since tools are normally invoked from command files or menus, descriptive 
names are better than short cryptic ones. Thus iconedit is better than ied. 

The frame header should contain the name of the program, optionally followed 
by a dash and additional information, as in: 



textedit - /tmp/file, dir: /usr/dg/doc 



W f 



The words in menus should be capitalized as they would be in a chapter heading: 



Close 
Move => 
Resize ■* 
Expose 
Hide 

Redisplay 

Quit 



This convention can be bent when the names in the menu correspond to already 
existing, non-capitalized command names. 
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Menus Showing Button 
Modifiers 



Interaction with Standard 
Menus 



Enable/Disable Menu Items 

Multi-Column Menus 
B.4. Panels 



When the behavior of a panel button depends on whether the user holds down a 
shift key, the button should have a menu summarizing the different actions, as in 
this menu from the Reply button in mailtool: 



reply 




Reply (all) 


[Shift] 


reply. Include 


[Ctrl] 


Reply (all), include 


[Ctrl][Shift] 



Standard SunView menus, such as the frame menu, should not be modified. 

When a user is used to seeing ‘Quit’ at the end of the frame menu, it is confusing 
to see a frame menu with a new item tacked on at the end. Equally confusing is a 
frame menu that comes up with an item other than ‘Close’ at the top. Thus, 
instead of deleting an item from a standard menu, applications should render the 
item inactive and “grayed-out.” And instead of adding a new item to a standard 
menu, applications should make a new menu, with the name of the standard 
menu at the top, followed by the application- specific commands. The standard 
menu then becomes a pullright subordinate to the custom menu, as in the exam- 
ple below: 





Close 


Dump Sere 


Move => 


Dump Regi 


Resize 


Print Dum 


Expose 


Vieu Dump 


Hide 




Redisplay 
Qui t 



Sometimes a menu has two different states, with different words appearing in the 
same position in a menu, depending on the current state. When the two states 
correspond to something being on or off, the words ‘Enable’ and ‘Disable’ 
should be used. Thus shelltool uses ‘Enable Page Mode’ and ‘Disable Page 
Mode’. 

Overly long menus should be avoided. Use menus with more than one column 
instead. 

The defaults for panel items given in this section are intended to promote con- 
sistency across applications and provide convenient building blocks for program- 
mers who don’t want to put a great deal of effort into designing fancy panels. 

The intent is not to rule out the use of non-default panel items. 
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Buttons The proper use of buttons is to allow the user to initiate commands. Button items 

should not be used to represent categories, modes or options — for these kinds of 
choices that imply a change of state, you should use toggle, choice or cycle 
items, as described in the next three sections. 

When creating a button, use the routine panel_button_image ( ) to create a 
button-like image, as in: 

t Dump Screen 



As with menu entries, capitalize buttons unless the button name matches some- 
thing else (for example, dbx(l) commands in dbxtool). If the button’s mean- 
ing can be modified by ( Control 1 or ( Shift 1 these modifiers should be indicated in 
the button’s menu. (For an example, see the picture of the Reply menu from 
mail tool, at the top of the preceding page.) 

In most cases, a button will remain visible all the time. However, when a tool 
has different states, and a button can only be used in some of those states, it is 
usually best to make the button invisible when it can not be invoked. Thus in 
mailtool, the Cancel button only appears when a letter is being composed. 

List of Non-Exclusive Choices A list of choices in which more than one choice can be selected at a time is best 

implemented with the item type PANEL_TOGGLE. The default for toggles is a 
list of check boxes: 

Optional Software: 

& Database 

□ Demos 

5^ Document Preparation Tools 

□ Games 

^Productivity Tools 

The example shows a vertical list; vertical or horizontal are both acceptable. 

List of Exclusive Choices A list of choices in which only one choice can be selected at a time can be 

displayed with all choices visible or with only the current choice visible. To 
show all the choices, use the item type panel_CHOICE. The default for choice 
items is a list of square pushbuttons, with the current choice marked by a dark- 
ened pushbutton: 

Drawing Mode: 0 Point 0Line 0 Rectangle 0 Circle El Text 

To show only the current choice, use PANEL CYCLE. This item type provides a 
symbol consisting of two circular arrows, which indicate to the user that he can 
cycle through choices, and serves to distinguish cycle items from text items: 

Category OsunView 
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Binary Choices 



Text Items 



Allocation of Function 
Between Buttons and Menus 



An item that is either on or off may be created using either PANEL_TOGGLE, 
PANEL_CYCLE or PANEL_CH0ICE. The picture on the left below is a toggle, 
the two in the middle are cycles, and the one on the right is a choice: 

Ef Grid Show Grid O Yes Grid C On Grid: B On B Of f 

Text items should have a colon after the label. 

For text items, it is recommended to have one or more buttons which cause the 
text item’s value to be acted on. In iconedit, for example, the user first enters 
a filename into the File: field, then presses the Load, Store, or Browse button in 
order to act on that filename. 

iconedit also allows the user to type ( Control-L 1 . [ Control-S 1 . or I Control-B 1 
into the File: field as accelerators for the buttons. Use of such accelerators 
(including carriage return to mean “enter”) is not recommended, as it conflicts 
with future plans for the use of non-printable characters. 

For the sake of consistency, whenever a tool reads from and writes to a file, it 
should label these buttons with Load and Store . 

Selecting a menu item is normally the same as either selecting a button or pick- 
ing from a choice item, boggle tool (6), for example, has a menu for restart- 
ing the game (as well as other things) but has no buttons. Each of the four menu 
items could have been represented by a button instead, lif e(6) does not have a 
choice item, but rather lets you choose a starting pattern with a menu. Thus the 
question of when to use a button (or choice) and when to use a menu arises. Here 
are some mles of thumb: 

□ Items on the frame menu should not be duplicated as buttons, with the possi- 
ble exception of a Quit button (see next paragraph). 

□ Some tools typically run all the time, such as mailtool. Others are nor- 
mally invoked only long enough to do a job, such as iconedit. Tools in 
the second category, if they have any other buttons, should also have a Quit 
button. 

□ If a tool has a commit operation, then it may have a Done button, which is a 
combination of close 107 plus commit. Thus mailtool has a Done button. 

□ A tool should never have a Close button, since this operation is already 
available via both a menu and the keyboard. 

□ If a custom menu is provided, the menu items should not all be duplicated as 
panel items (buttons or choices), boggletool and lif e are examples of 
programs that have functionality in custom menus that are not duplicated as 
panel items. 

□ When a button and a menu item perform the same function, their labels 
should be identical. 



107 If the panel is in a subframe, the Done operation implies disappearing from the screen rather than 
closing, since subframes can’t become iconic. 
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B.5. Mouse Button Usage 

Allocation of Function Use of mouse buttons should be consistent with the rest of SunView. The left 

Between Mouse Buttons button should only be used to make selections. The right button should only be 

used to bring up menus. 108 

There is some discretion involved in the use of the middle button, however. In 
most of SunView, the middle button is used to adjust a selection. In text and 
shell windows, for example, the left button is used to mark the starting point of a 
selection, and the middle button is used to extend the selection. Similarly, in a 
pixel editor that allowed you to select regions, clicking the left button on a region 
could select just that region, and clicking the middle button on another region 
could add that region to the selection. On the other hand, in a tool that allowed 
you to move objects, the middle button could move an object, and 
[ Control 1 -MIDDLE button could re-size it, which would be consistent with the 
way icons and frames are moved and re-sized. As a third alternative, in the 
iconedit drawing program the left button draws pixels (which is a kind of 
selecting) and the middle button erases. 

The best use of the middle button is still being discussed. Future versions of this 
guideline may specify more exactly how the middle button should be used. For 
now, the most common use is to extend the selection, and the next-most common 
is to move a graphic object. 

It is acceptable to use the mouse buttons as accelerators for common operations. 
The only caveat is that any accelerators should also be available from a menu or 
panel item. Thus in SunView clicking on a tool with the middle button moves 
the tool, but you can also move a tool using the frame menu. 

Some operations, on the other hand, cannot be invoked from a menu or panel 
button. In such cases the mouse is the only means of invoking the operation. For 
example, in iconedit you use the mouse for drawing, and the drawing opera- 
tions are not available from a menu or button. 

B.6. Cursors An application program should not do anything other than change the shape of 

the cursor when the cursor is moved into a new window, textedit presents a 
good example of using the cursor to alert the user that input is interpreted dif- 
ferently in different regions: The cursor is a thin diagonal arrow in the 
textsub window, a fat horizontal arrow in the scrollbar, and a diamond in the 
scrollbar buttons. 

B.7. Icons Tools should pack as much information as possible into their icons, clock and 

per f meter are examples of tools that make good use of icon real estate, tex- 
tedit is an example of a tool that could make better use of its icon. For exam- 
ple, it could contain a representation of the text being editing in a 1 point font. 
Small as that is, you can tell at a glance if you are editing C code or a mail mes- 
sage. 



Using Mouse Buttons for 
Accelerators 



108 p eo pie who want to hold the mouse with their left hand can put the “menu button” on the left and the 
“select button” on the right by setting the Left _Handed option in the Input category of def aultsedit. 
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Some icons, like the round face used by clock and the page with the protruding 
pencil used by textedit, have images with non-square outlines. These icons 
have the area outside of the image outline filled in with the root grey pattern so 
that the icons will blend in with the default SunView background. While this 
looks good when the background is in fact the default pattern, it is not recom- 
mended, since users can choose an arbitrary background pattern for SunView. 
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Converting SunWindows Programs to 

Sun View 

This appendix gives some guidelines for converting programs written using 
SunWindows to SunView. There are two classes of programs covered: those 
that create a tool and subwindows, and programs that call gfxsw_init( ) to 
take over an existing window or the console. 

Programs that fall outside these classes are probably UNIX-style programs that do 
not use windows at all. The conversion of such programs is in effect the subject 
of this whole manual. If you want to convert such a program to SunView, pay 
particular attention to Chapter 2, The SunView Model, and the specific discussion 
of Notifier interaction under Porting Programs to SunView in Chapter 17, The 
Notifier. You may also find some of the discussion later on in this appendix 
under Section C.2, Converting Gfxsubwindow-Based Code, helpful. 
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C.l. Converting Tools It is reasonably straightforward to convert tools that create windows in SunWin- 

dows to the SunView interface because they should already have the appropriate 
architecture. SunView programs, like SunWindows programs, have three parts: 
initialization of static objects, starting up window system interaction, and the 
routines that are called after the tool is running in the window system. 

General Comments When porting to SunView, you should look through all of your code for SunWin- 

dows function calls. If you see one, the odds are that you are going to have oth- 
ers. Look for every occurrence of the call and then change it to the new format. 
Since the SunView libraries are mixed in with the SunWindows libraries, you 
can mix the two types of functions calls, and not get any compilation errors. But 
you will get some inconsistent results. 

Programming Style Changes 

Object typedef s The capitalized typedef s for window system objects (applied to Panels, 

Panel_items and Panel_settings in 2.0 SunWindows) have been 
extended to nearly all SunView objects, including: 

Canvas Pixrect 

Cursor Pixwin 

Frame Rect 

Icon Rectlist 

Menu Scrollbar 

Panel Textsw 

Panel_item Tty 

Pixfont Window 

You should convert to using these data types in the interests of future compatibil- 
ity. See Object Handles in Chapter 3, Interface Outline, for more information on 
these types. 

Attribute Value Interface In SunView, the attribute value interface, introduced for panel subwindows in 2.0 

SunWindows, has been extended to all types of windows. Attributes for all win- 
dow types are set and obtained with the same two calls, window set ( ) and 
window_get ( ) . 

All window types are created with the same call, window_create ( ) . 

CAUTION The most frequently used SunView calls use attribute lists, and therefore 
must be null-terminated. SunView will only complain about a malformed 
attribute list at run time. 
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New Objects 



Canvas Subwindows 



Text Subwindows 



Scrollbars 



Most of the data types in the above list are objects new in SunView. Many 
objects in SunWindows correspond to objects in SunView, for example: 

tool => Frame 

ttysw =* Tty 

Some objects such as the graphics subwindow and empty subwindow are not 
supported in SunView 109 . There are new objects that partially take their place. 

The canvas subwindow is a general-purpose drawing subwindow, which can 
replace gfx sub windows and empty subwindows. The size of the canvas you 
draw on need not be the same as the size of the window it is displayed in; you 
can create scrollbars to let the user adjust the visible part of the canvas. For a 
demonstration of the various canvas attributes, run the program 
lusr/demo/ canvas demo 

These allow for the display and editing of text in a scrollable window. The user 
can perform various actions on the text, including saving the text, searching in 
the text, and editing the text without the programmer having to deal with these 
interactions. 

Since there was no such window in SunWindows, your application may have had 
to use a gfx subwindow, a set of panel message items, or some strange technique 
involving ttysw_input ( ) or piping to a tty subwindow to display text; the 
text subwindow can replace all these uses. 

Scrollbars can be attached to windows. In particular, the use of scrollbars with 
retained canvases makes it very easy to draw a fixed- size image without regard 
for window size changes. 



109 You can still compile and run code that uses these, but Sun does not intend to develop them further. 
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Objects in Common between 
SunView and SunWindows 

Cursors Cursors have changed. They are now type Cursor, and all calls relating to 

them have changed. Type Cursor should be looked at as a pointer to the struc- 
ture containing the cursor information. Here is how you would define a cursor: 




Once having created a cursor, you call window set ( ) to add it to a window, 
as in the following code fragment: 




You now refer to all your cursors by the handle you get from 
cursor create ( ) . Cursors have their own create, destroy, copy, set, and get 
routines, as well as a number of attributes with no corresponding functionality in 
SunWindows. 

Icons Icons have changed. They follow the same pattern as cursors; you define the 

data, create a pixrect, and then call icon_create ( ) at run time. These also 
have their own create, destroy, set and get routines, although there are fewer attri- 
butes associated with them. 



4bsun 

microsystems 



Revision A, of March 27, 1990 







Appendix C — Converting SunWindows Programs to SunView 437 



Menus 



Input Events 



The new walking menu package uses the attribute value interface. It has many 
more features than the old menu package. It does not support the stacking menu 
style of SunWindows. 110 



Menus also have their own routines and are created via function calls instead of 
being user-loaded data structures. They use the pointer type Menu for their han- 
dles instead of struct menuptr. One way to create them is to write a spe- 
cial menu init ( ) proc which loads them into their structures correctly. In 
your menu_init ( ) , you have something like 



ml_items = menu_create( 

MENU_STRING_ITEM, "insert", INSERT, 

MENU_STRI NG_I TEM , "copy", COPY , 

MENU_STRING_ITEM, "replace", REPLACE, 

MENU_STRI NG_I TEM , "move", XLATE , 

MENU_STRING_ITEM, "delete", DELETE, 

MENU_STRING_ITEM, "HELP", DRAWHELP , 

0 ); 



Menu values from menu_get ( ) or menu_show( ) are returned as 
caddr_t’s. Be sure your types match. 

NOTE The old menu_display ( ) and the new menu_show( ) routines have a dif- 
ferent order for the arguments. 

The inputevent structure has not changed. However, you no longer have to 
generate events yourself in “selectedroutines via calls to 
input_readevent ( ) . Instead, windows now have event handlers that are 
passed pointers to Event structures. 

There are a number of macros for making input events easier to deal with in Sun- 
View, so instead of having something like ie - > ie code you have 
event_id ( ie ) , resulting in more readable code. 

Event types are not pointers, so you have to distinguish between 

Event *ie; 

and 

Event ie ; 

in your code. You can use either, because the event functions don’t just manipu- 
late a handle as, for example, the cursor functions do. See Object Handles in 
Chapter 3, Interface Outline , for an explanation of when handles are pointers and 
when not. 



110 This is still available in the frame and root menus if you disable SunViewlWalking_Menus in 
defaultsedit. 
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Setting up Input Event Handling All the input events can be set up from the window_create ( ) call or 

window_set { ) calls. Calls to win_*inputmask ( ) are all replaced by 
these window_set( > and window_create( ) calls. 

The distinction between “pick” and “keyboard” events is new in Sun View, hav- 
ing been added to support the notion of a split input focus. 

CAUTION Be careful that when you are setting mouse events, you are modifying the 
WIN _*_ PICK _ EVENTS ai) d when you are setting keyboard events you 
modify WlN_*_KEYBOARD_EVENTS. You may get inconsistent results if 
you modify pick events on the keyboard mask. 



Sigwinch Handling Canvas event procedures no longer need all the gfx support for flag checking. 

Resize and repaint events are separately handled by the procedures you supply 
via the CANVAS_RESlZE_PROC and CANVAS_REPAlNT_PROC attributes. 
These procedures mean you should not try to catch sigwinch signals (and in fact, 
if you do, you will have problems; see below). 

Windows Making windows is very straightforward in SunView. Each window type has a 

handle — so instead of the inconsistent use of handles and fd’s to describe a 
window and manipulate it, you only use the window handle. You need to go 
through your code and update all the reference to the old tool_... handle types 
in the code. After you find them, locate all the function calls referring to them 
and update them to SunView window_set ( ) and window_get ( ) calls. 
Almost every window operation is supported by the attribute value interface; 
however, some low-level routines that are documented in the SunView System 
Programmer’s Guide may still require window names or fd’s. 



window_get ( ) is used to get an attribute of a window. It returns a caddr_t 
back to you, which must be cast into the appropriate type. So loading something 
into a rect struct would involve something like: 



r 


Rect 


win_size; 


\ 




Canvas 


canvas ; 






canvas 


= window__create ( base_frame, CANVAS, 0); 






win_size= *((Rect * )window_get( canvas, WIN_RECT) ) ; 










/ 



NOTE Be sure to cast values returned from get ( ) routines to the correct type. 

The above * ( ( Rect *)...) is needed otherwise you will get an ’incompatible 
type’ message from the compiler. 



Panels Most of the panel interface was already using an attribute value interface in 2.0 

SunWindows. panel_create ( ) panel_set( ) and panel_get ( ) should 
be changed to window_create ( ) , window_set ( ) and window_get ( ) . 

The PANEL_CU ( ) macro was superseded by ATTR_COL ( ) and 
ATTR_ROW ( ) . 
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Signals If you are catching signals, then you should read the documentation on signals in 

Section 17.2, Restrictions , in the Notifier chapter. There are several that the 
Notifier now catches on your behalf. 

You should no longer be catching SIGWINCH signals. If you do, your program 
may never appear on the screen as it will start catching the signals and redrawing 
endlessly on the screen, which may not be visible. 

Prompts Instead of using the menu_prompt ( ) facility of SunWindows, you should use 

the alerts package to prompt the user, or if necessary use pop-up subframes and 
window_loop ( popup_ frame ) when prompting the user. The filer example 
programs in Chapter 4, Windows, uses the alerts package to implement a pop-up 
confirmer. 

menu_prompt ( ) is documented here for completeness. The definitions used 
by menu_prompt ( ) are: 

struct prompt { 

Rect prt_rect; 

Pixfont *prt_font; 
char *prt_text; 

} 

menu_prompt( prompt, event, windowfd) 
struct prompt *prompt; 

struct inputevent * event; 
int windowfd; 

menu_prompt ( ) displays the string addressed by prompt ->prt_text 
using the font prompt - >prt_f ont. prompt - >prt_rect is relative to 
windowfd. If either the r_width or the r_height fields of 
prompt - >prt_rect has the value PROMPT FLEXIBLE, that dimension is 
chosen to accommodate all the characters in prompt - >prt_text. 

The fullscreen access method is used to display the prompt. After displaying the 
prompt, menu prompt ( ) waits for any input event other than mouse motion. 
It then removes the prompt, and returns the event which caused the return in 
event, windowfd is the file descriptor of the window from which input is 
taken while the prompt is up. 
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Table C-l 


S unWindows => SuriView Equivalences 


In S unWindows 


In Sunview 


tool = tool_make ( ) 


Frame frame = window_create(NULL, FRAME, ... , 0); 


tool_parse_all 


FRAME_ARGS or FRAME_ARGC_PTR_ARGV 
attributes to window_create ( NULL , FRAME , ... , 0 ) 


tool_install ( ) 
tool_select( ) 
tool_destroy( ) 


window_ma in_loop ( frame ) ; 


or, individually , 




tool_install( ) 


win_SHOW attribute 


tool_select( ) 


window_main_loop( ) , notify_dispatch( ) or notify_start( ) 


tool_destroy( ) 


window_destroy(baseframe) or window_done ( any window ) 


signal (SIGWINCH, sigwinch) 


RES I z E_PROC and REPAINT_PR0C attribute 


TOOLSW_EXTENDTOEDGE 


WIN_EXTEND_TO_EDGE 


win_grabio( ) 


WIN_GRAB_ALL_INPUT attribute 


struct toolio 


win_event_proc for window events. Other events, timers, etc. 
handled by individual calls to the Notifier to set up or interpose specific procs. 
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C.2. Converting Programs that run in gfxsubwindows are designed to take over an existing win- 

Gfxsubwindow-Based dow. In SunView you must create a tool for such programs to run in. One limi- 

Code tation of this approach is that the SunView version of the application must run 

under suntools; the old gf xsw_init ( ) call would create a SunWindows 
environment if run on the “bare” Sun console. One major advantage gained by 
moving to SunView is that your code can use scrollbars. 



Basic Steps 



□ Include <suntool/sunview. h> and <suntool/canvas.h>. 

□ Remove all window-related # include statements; these will probably be 
included by sunview. h. 

□ Declare a Frame and a Canvas. 

□ Replace gf xsw_init ( ) with calls to create the frame and canvas. 



Replacing Tool Interaction 

Styles of Damage Checking Many gfx subwindow programs (and many of the Sun demos) call 

gf xsw_init ( ) to take over a window, then run in a loop as they compute and 
draw an image in the gfx subwindow. At some point in the loop they check for 
damage to or alteration of the size of the gfx subwindow and handle it accord- 
ingly. 

In SunView, the coexistence of your program with the window system is less 
hidden from you. Read Chapter 2, The SunView Model , to understand how this 
coexistence works. In converting programs, you must ensure the Notifier runs at 
regular intervals so that window events such as close, quit, etc. are handled 
appropriately. 

Consult Chapter 17, The Notifier, for more information. 

You can either (1) set up your program so that, after initialization, control passes 
to the Notifier, which you have set up to call your imaging/computation routine 
periodically, or (2) let control continue to pass to your code, and change the pro- 
gram to call the Notifier at regular intervals. 



Either the Notifier Takes Over In the first case, you set up your imaging/computation routine as a function that 

is called when a timer expires. Do this by calling 

notif y_set_itimer_f unc ( ) . If you want your imaging/computation rou- 
tine to blaze away non-stop (causing other programs to run more sluggishly), you 
request the timer function be called as soon as the Notifier has handled window 
events for you by giving the timer the special value 
&NOTIFY POLLING ITIMER. 



r 




N 




(void) notify set itimer 


func ( frame, my_animation , 




ITIMER_REAL , 


&NOTIFY_POLLING_ITIMER, ITIMER_NULL) ; 






) 



If your code sleep ( ) ’s on a regular basis, then you should be able to modify it 
so that the Notifier calls your imaging/computation routine at the same interval. 
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The program spheres in Appendix A, Example Programs, is an example of this 
style of interaction. 

Or Your Code Stays in Control On the other hand, if your program just loops, perhaps while ( - - gf x_reps ) , 

then you could add to the loop a call to notif y_d is patch ( ) . This will han- 
dle window system events and return. 

The program bounce in Appendix A, Example Programs , is an example of this 
style of interaction. 

If you do this then your program has to detect when the user has ‘Quit’ from the 
menu: see Finishing Up below. 

NOTE gf x reps in a gfx subwindow program is set to a large number (200,000), but 
the user can change it through the command line argument 
-n number _of ^repetitions. 

Handling Damage The Notifier will handle moving the window, resizing it, etc. However, resulting 

damage to your canvas may need to be repaired. In the gfx subwindow, 
GFX_DAMAGED is set whenever a SIGWINCH is received. In addition 
GFX_RE START is set if the size of the window has changed or if the window is 
not retained. GFX_DAMAGED is set as a hint for you to call 
gf xsw_handlesigwinch ( ) , which would clear up the damaged list and if 
the window was retained it would repaint the image for you. GFX_RESTART is 
set as a hint that the window had to be rebuilt, either because of damage and the 
window is not retained, or because of a resize. 

Many situations that you would need to handle yourself in a gfx subwindow are 
rendered superfluous by attributes of the canvas subwindow, such as 
CANVAS_AUTO_CLEAR, etc. For starters, canvases are retained by default; if 
your canvas has scrollbars and is retained, then you need not be concerned with 
resize events. Nevertheless, you may need to be aware when you must rebuild or 
repair your image. Read the Canvases chapter for more information. 

Rather than setting a flag, SunView calls your own procedure if you specify one 
with the CANVAS_REPAlNT_PROC and C ANVAS_RES I Z E_PROC attributes. 
These are called with useful parameters for their tasks. 

You can modify your code so that the repair activity that used to take place after 
noticing the flags have been set now takes place in the procs themselves, or you 
can write the procs so they set flags similar to the GFX RESTART and 
GFX REPAINT flags and return, and leave your repair code almost untouched. 
Or, depending on your application, you can set up your canvas so that the win- 
dow system handles all damage. 

The gf xsw Structure The gf xsw structure has fields in it that carry useful information. Comparable 

information is available in SunView, so you can declare and setup a comparable 
structure in SunView. The bounce program in Appendix A, Example Programs, 
does this. 

Gfx subwindow -based programs use the gf x- >gf xsw_rect to determine the 
geometry of the window they are drawing in. Since the starting point of this was 
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Finishing Up 



Miscellaneous 



relative to the gfxsw, it was always 0. 111 In SunView the width and height of the 
canvas you draw in are available through the canvas attributes CANVAS_WIDTH 
and CANVAS HEIGHT. The fields of the gfx- >gfxsw_rect correspond to 
these attributes as follows: 

coord r_left, r_top; are both = 0 

short r_width, r height; are the CANVAS_WIDTH and 

CANVAS_HEIGHT attributes. 

As described above, you can use your own GFX RESTART and GFX REPAINT 
flags. 

If you care about the gfxsw command line arguments, insert code into your 
program’s argv , argc parsing loop to handle the gfx options that used to be 
taken care of for you. The bounce program has reasonable code to do this. 

If your imaging routine is in control and periodically calls the Notifier, then when 
the window is quit your routine must know that this has occurred. Otherwise, the 
imaging routine will continue to draw in a window that has been destroyed, and 
you will see error messages like 



WIN ioctl number C0146720: Bad file number 

k, ^ 

until you kill the program. 

What you must do is interpose in front of the frame’s destroy event handler so 
that your program will know when the frame goes away. See the item on Getting 
Out in Porting Programs to SunView in the Notifier chapter. 

If your program exits on its own, then it can call window_done ( ) to destroy 
its windows. This will invoke your interposed notice-destroy routine (which may 
or may not matter depending on what it does). It will also call the standard 

Are you sure you want to Quit? 

alert unless you set FRAME_NO_CONFlRM. 

gf xsw getretained ( ) is equivalent to the CANVAS_RETAINED attribute. 
Canvases are retained by default. 

gf xsw init ( ) doesn’t consume the gfxsw command line options -r, 

-n Number of repetitions, etc; your code may do strange things with its argu- 
ments to deal with this. 



111 Many of the demos supplied by Sun are confused on this point and go through unnecessary steps. 
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Two Examples Listings of two programs converted from SunView are in Appendix A, Example 

Programs. 

bounce The first is a new version of bouncedemo(6). It now draws its bouncing square 

in a canvas. It has code to parse the standard gfx subwindow command line 
arguments. It preserves the original while (gfx->gfx_reps ) {...) loop 
structure of bouncedemo by calling notif y dispatch ( ) at the top of the 
loop. Because it is running in a loop it must detect when the user has ‘Quit’ the 
window, so it interposes before its frame’s destroy routine using 
notif y_interpose_destroy_f unc ( ) . The routine that is called just 
sets a flag so the program knows to exit from the loop. 

spheres The second is a version of spheresdemo(6). It now draws its shaded spheres 

in a canvas with scrollbars, so you can see all the image in a small window. It 
handles the notification of SunView events by asking the Notifier to call the 
drawing routine (my_animation ( ) ) as often as possible, using 



f — 


(void) notify_ 


set_itimer func(frame, my animation, 






ITIMER 


REAL, &NOTIFY_POLLING_ITIMER, ITIMER_NULL) ; 




V 






J 



Since the drawing operation is under the control of the Notifier, the Notifier can 
control the program, so the while ( gf x - > gf x_reps ) { ... } loop structure 
is replaced by a call to window_main_loop ( ) ; this will terminate the pro- 
gram when the user chooses ‘Quit’ from the frame menu. 

spheres detects when it is made iconic by interposing in front of the frame’s 
client event handler using notif y_interpose_event_f unc ( ) . The rou- 
tine that is called calls the normal even t_f unc, then checks to see if the frame 
has changed state: if it has been closed it turns the notify timer off altogether, so 
the drawing routine is no longer called; if it has been opened the timer is set back 
to immediate polling. 

bounce should do this also — there is little point in drawing when iconic unless 
you are drawing a single compute-intensive image. 



Detecting when the Program is 
Iconic 
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converting programs to SunView 
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write a prompt. . . read a reply, 200 
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crosshair gap, 239 
crosshair length, 239 
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definition of, 234 
fullscreen crosshairs, 239 
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interface summary, 291 
rasterop, 238 
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cursor constants 
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cursor functions, continued 

cursor_create () , 236, 293 
cursor_destroy () , 236, 293 
cursor_get ( ) , 236, 293 
cursor_set ( ) , 236, 293 
CURSOR__TO_EDGE, 239 
cycle panel item, 161 

D 

data types, 294 
caddr_t, 22 
object handles, 22 
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default colormap segment, 103 

default system font, 33 

DEF I NE_I CON_FROM_I MAGE (> , 32, 242 

DESTROY_CHECKING, 274 

DESTROY_CLEANUP, 274 

DE STROY_PROCES S_DEATH, 274 

destroying windows 

FRAME_NO_CONF IRM, 354 
destruction of objects, 274 
disable Quit confirmation 

FRAME_NO_CONF IRM, 33, 354 
dispatching events 

calling the Notifier explicitly, 277 
calling the Notifier implicitly, 277 
display 

batching, 98 

canvases and gfxsw’s in multiple plane groups, 114 
determining if in color, 108 
enable plane, 113 
locking, 97 

locking and batching interaction, 100 
overlay plane, 1 13 
plane group, 1 13 
software double-buffering, 108 
speed, 96 

distribution of input in a window, 80 

E 
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ASCfl event codes, 76 

canvas space vs. window space, 63, 88 

definition of, 70 

function key event codes, 78 

keyboard focus event codes, 78 

META event codes, 76 

mouse button event codes, 76 

mouse motion event codes, 76 

panel space vs. window space, 181 

reading events explicitly, 87 

relationship to Notifier, 15 

repaint and resize event codes, 77 

shift key event codes, 79 

timeout, 268 

using an event with alerts, 192 
window entry and window exit event codes, 77 
event codes, 301, 72 
BUT (),76 
KBD_DONE, 78 
KBD_REQUEST, 78 



event codes, continued 
KBD_USE, 78 
KEY_LEFT, 78 
KEYJRIGHT, 78 
KEYJTOP, 78 
LOC_DRAG, 63, 76 
LOC_MOVE, 76 
LOCJRGNENTER, 77 
LOC_RGNEX I T, 77 
LOC_STILL, 76 
LOCJTRAJECTORY, 76 
LOC_WINENTER, 77 
LOC_WINEXIT, 77 
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WIN_REPAINT, 63, 77 
WIN_RESIZE, 63, 77, 273 
WIN_STOP, 78 
event descriptors, 304 
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WIN_MOUSE_BUTTONS, 80, 304 
WIN_NO_EVENTS, 80, 304 
WIN_UP_ASCII_EVENTS, 80, 304 
WIN_UP_EVENTS, 80, 304 
event handling 

at the Notifier level, 262 
in canvases, 63 
in panels, 177 
event procedure 
form of, 71 

writing your own for a canvas, 63 
writing your own for a panel item, 179 
event state retrieval macros 
event_action ( ) , 86 
event_ctrl_is_down () , 86 
event_is_ascii () , 86 
event_is_button ( ) , 86 
event_i s_down ( ) , 86 
event_is_key_lef t ( ) , 86 
event_is_key_right ( ) , 86 
event_is_key_top () , 86 
event_is_meta (), 86 
e vent_i s_up ( ) , 86 
event_meta_is__down () , 86 
event_shift_is_down () , 86 
event_shif tmask ( ) , 86 
event_time ( ) , 86 
event_x () , 86 
event_y () , 86 
event state setting macros 

event set down(),87 
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event state setting macros, continued 
event_set_id () , 87 
event_set_shiftmask () , 87 
event_set_time () , 87 
event_set_up ( ) , 87 
event_set_x ( ) , 87 
event_set_y ( > , 87 
event stream, 70 
example programs, 359 
animatecolor, 110, 409 
bounce, 416 
color manipulation, 404 
coloredit, 106, 404 
colormap manipulation, 404 
converting terminal-based programs, 200 
creating menus, 382 
detool, 394 

discussion of image browser _1 program, 43 
discussion of imagebrowser 2 , 46 
discussion of simple file manager, 36 
filer, 36, 359 
font menu, 382 

gfx subwindow-based demos converted to SunView, 416 

gfxsw_init to SunView, 416, 421 

image _browser_l , 370 

image _browser_2, 374 

list files in tty subwindow, 34 

minimal SunView program, 29 

not ify_di spat ch () , 200, 416 

notify_set_itimer_func () , 421 

resize_demo, 45, 273, 389 

row/column space in a window, 374 

showcolor, 104 

simple file manager, 359 

simple panel window, 31 

spheres, 421 

subwindow layout, 370 

tty subwindow escape sequences, 379 

tty subwindow I/O, 379 

tty jo, 379 

typein, 400 

F 

f cntl(2), 260, 264 
file descriptor leakage, 51 
file descriptor usage, 50 
file descriptors, counting, 51 
filer, 36 

flow of control in Notifier-based programs, 17 
font functions 

pf_default () , 33, 94 
pf _open ( ) , 33 
frame 

command line frame attributes, 358 
definition of, 12 
fitting around subwindows, 34 
frame header, 14 

layout of subwindows within a frame, 44, 45, 273, 389 
menus, 14 

modifying destruction using the Notifier, 273 
modifying open/close using the Notifier, 271 
table of attributes, 354 
frame attributes, 354 



frame attributes, continued 

FRAME_ARGC_PTR_ARGV, 32, 354 
FRAME_ARGS, 48, 354 
FRAME_BACKGROUND_COLOR, 103, 354 
FRAME_CLOSED, 354 
FRAME_CLOSED_RECT, 354 
FRAME_CMDLINE_HELP_PROC, 354 
FRAME_CURRENT_RECT, 354 
FRAME_DEFAULT_DONE_PROC, 354 
FRAME_DONE_PROC, 354 
FRAME_EMBOLDEN_LABEL, 354 
FRAME_FOREGROUND_COLOR, 103, 354 
FRAME_ICON, 32, 354 
FRAME_INHERIT_COLORS, 103, 354 
FRAME_LABEL, 32, 354 
FRAME_N 0_CONF I RM, 33, 354 
FRAME_NTH_SUBFRAME, 355 
F RAME_NT H_S UBW I N D 0 W, 355 
FRAME_NTH_WINDOW, 355 
FRAME_OPEN_RECT, 355 
FRAME_ACT I ON_PROC, 355 
FRAME_ACT I VE, 355 
FRAME_SHOW_LABEL, 32, 38, 355 
FRAME_SHOW_SHADOW, 355 
FRAME_SUBWINDOWS_AD JUST ABLE, 355 
FR AME_PROPS_ACTION_PROC , 39 
FRAME_PROPS_ACTTVE, 39 
FRAME_SHOW_SHADOW, 42 
f ree(3), 283 
function keys, 78 

G 

generate procedure 
for menu, 226 
for menu item, 225 
for pull-right, 228 

generate procedure operation parameter values 
MENU_DI SPLAY, 224 
MENU_D I SPLAY_DONE, 224 
MENU_NOTIFY, 224 
MENU_NOTIFY_DONE, 224 
getitimer(2), 259 
gfx subwindow 

p w_u se_f a st_mono chrome ( ) , 114 
converted demo programs, 416, 421 
converting to SunView, 441 
demo programs converted to SunView, 416 
monochrome in multiple plane groups, 114 

H 

header files 

overview, 21 

<suntool/canvas . h>, 53 
<suntool/icon . h>, 241 
<suntool/menu .h>, 203 
<suntool /panel ,h>, 139 
<suntool /scrollbar .h>, 152,245 
<suntool/seln .h>, 255 

< sunt ool / sunview . h>, 21 
<suntool/textsw.h>, 117 

< sunt ool /tty .h>, 195 
<sunwindow/attr . h>, 283 
<sunwindow/cms mono. h>, 103 
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header files, continued 

<sunwindow/pixwin .h>, 89 
<sunwindow/rect .h>, 45 
<sunwindow/win_cursor . h>, 234 
<sunwindow/win_input .h>, 67 
<sunwindow/window_hs .h>, 67, 89 

help 

interface summary, 298 
table of attributes, 298 
table of functions and macros, 298 
help attribute, 298 
help attributes 

HELP_DATA, 298 
help functions and macros, 298 

I 

icon, 241 

definition of, 15 

interactive editor for icon images, 242 
interface summary, 299 
Loading Icon Images At Run Time, 244 
modifying the icon’s image, 243 
table of attributes, 299 
table of functions and macros, 300 
icon attributes, 299 
I CON_FONT, 299 
I CON__HE I GHT, 299 
I CON_IMAGE, 299 
I C0N_I MAGE_RE CT, 299 
ICON_LABEL, 299 
ICON_LABEL_RECT, 299 
ICON_WIDTH, 299 
icon functions and macros, 300 

DEF I NE_I CON_FROM_I MAGE {) , 32, 242, 300 
icon_create () , 242, 300 
i con_de s t roy ( ) , 300 
icon_get ( ) , 300 
icon_set ( ) , 300 
image browser _1 , 43 
image browser _2, 46 
images 

in icons, 242 
in menus, 209 
mpr_static ( ) , 209, 242 
using images generated with iconedit, 209, 242 
include files — see “header files”, 21 
initiating event processing, 27 
input, 67 

ASCH events, 80, 304 
designee, 82 
environment, 69 
event descriptors, 80 
event macros, 86, 87 
flow of control, 87 
focus, 81 
focus control, 81 
grabbing all input, 82 
in canvases, 63 
interface summary, 301 
keyboard focus, 78, 81 
keyboard mask, 81 
mask, 81 thru 85 



input, continued 

mouse motion, 76 
pick focus, 81 
pick mask, 81 
reading, 87 
recipient, 82 

refusing the keyboard focus, 78 
releasing, 82 
shift state, 87 
state, 86 

table of event codes, 72, 301 
table of event descriptors, 304 
table of input-related window attributes, 305 
Virtual User Input Device ( VUID ), 70 
input event codes 

SCROLL_REQUEST, 73, 302 
interposition, 261, 270 thru 276 
interval timers, 268 thru 270 
ioctl(2), 260 
it_interval struct, 270 

K 

KBD_DONE, 78 
KBD_REQUE ST, 78 
KBD_USE, 78 
KEY_LEFT, 78 
KEY_RIGHT, 78 
KEY_TOP, 78 
keyboard focus, 78 

L 

layout of items within a panel, 147 

layout of subwindows within a frame, 44 

libraries used in SunView, 21 

LOC_DRAG, 76 

LOC_MOVE, 76 

LOC_RGNENTER, 77 

LOC_RGNEXIT, 77 

LOC_STILL, 76 

LOC_TRA JECTORY, 76 

LOC_WINENTER, 77 

LOC_W INEXIT, 77 

locator, see mouse 

locator motion event codes, 76 

M 

memory leaks, 155 
Menu, 297 
menu 

attributes to add pre-existing menu items, 217 

basic usage, 206 

callback procedures, 222 

client data, 210 

default selection, 23 1 

destruction, 220 

display stage of menu processing, 223 
example program, 382 
for panel items, 145 
generate procedure, 224 
inactive items, 213 



449 - 





Index — Continued 



menu, continued 

initial selection, 231 

interface summary, 306 

notification stage of menu processing, 224 

notify procedure, 210, 229 

pull-right, 203 

searching for a menu item, 221 
shadow, 210 
table of attributes, 306 
table of functions, 312 
table of menu item attributes, 310 
user customizable attributes, 232 
walking, 203 
menu attributes, 306 

MENU_ACT I ON_IMAGE, 219, 306, 310 
MENU_ACT I ON_I TEM, 219, 306, 310 
MENU_ACT I ON_PROC, 310 
MENU_APPEND_ITEM, 217, 306, 310 
MENU_BOXED, 213, 232, 306, 310 
MENU_CENTER, 306, 310 
MENU_CLIENT_DATA, 210, 306, 310 
MENU_COLUMN_MA JOR, 306 
MENU_DEFAULT, 306 
MENU_DEFAULT_I TEM, 231, 306 
MENU_DEFAULT_SELECT I ON, 231, 232, 306 
MENU_DESCEND_FIRST, 221, 306 
MENU_FEEDBACK, 216, 310 
MENU_FIRST_EVENT, 306 
MENU_FONT, 210, 215, 232, 306, 310 
MENU_GEN_PROC, 224, 225, 226, 306, 310 
MENU_GEN_PROC_IMAGE, 310 
MENU_GEN_PROC_ITEM, 224, 310 
MENU_GEN_PULLRIGHT, 228, 310 
MENU_GEN_P ULLR I GHT_I MAGE , 219, 228, 306, 310 
MENU_GEN_PULLRIGHT_ITEM, 219, 228, 306, 310 
MENU_IMAGE, 310 

MENU_I MAGE_I TEM, 207, 211, 219, 307, 310 

MENU_I MAGES, 209, 219, 307 

MENU_I NACT I VE, 213, 310 

MENU_INITIAL_SELECTION, 231, 232, 307 

MENU_INITIAL_SELECTION_EXPANDED, 232, 307 

MENU_IN IT I AL_SELECT I ON_SELECTED, 232, 307 

MENU_INSERT, 216, 217, 307 

MENU_INSERT_ITEM, 217, 307 

MENU_INVERT, 311 

MENU_ITEM, 208, 215, 219, 307 

MENU_ JUMP_AFTER_NO_SELECT I ON, 232, 307 

MENU_JUMP_AFTER_SELECT ION, 232, 307 

MENU_LAST_EVENT, 307 

ME NU_LEF T_MARG I N, 212, 232, 307, 311 

MENU_MARGIN, 212, 213, 232, 307, 311 

MENU_NCOLS, 213, 307 

MENU_N ITEMS, 215, 307 

MENU_NOT IF Y_PROC, 308 

MENU_NROWS, 213, 307 

MENU_NTH_I TEM, 215, 308 

MENU_PARENT, 308, 311 

MENU_PULLRIGHT, 208, 215, 311 

MENU_PULLRIGHT_DELTA, 232, 308 

MENU_PULLRIGHT_IMAGE, 219, 308, 311 

MENU_PULLRIGHT_ITEM, 218, 219, 308, 311 

MENU_RELEASE, 216, 220, 311 

MENU_RELEASE_IMAGE, 311 

MENU_REMOVE, 217, 308 



menu attributes, continued 

MENU_REMOVE_I TEM, 217, 308 
MENU_REPLACE, 217, 308 
MEN U_REP LACE_ I TEM, 217, 308 
MENU_RIGHT_MARGIN, 212, 232, 308, 311 
MENU_SELECTED, 308, 311 
MENU_SELECTED_ITEM, 231, 308 
MENU_SHADOW, 210, 214, 232, 308 
MENU_STAY_UP, 308 
MENU_STRING, 208, 215, 311 
MENU_STRING_ITEM, 207, 211, 219, 308, 311 
MENU_STRINGS, 219, 308 
MENU_TI TLE__I MAGE, 210, 309 
MENU_TITLE_ITEM, 210, 309 
MENU_TYPE, 309, 311 
MENU_VAL I D_RE SULT, 309 
MENU_VALUE, 207, 211, 311 
menu callback procedures 
generate procedures, 224 
notify and action procedures, 229 
menu data types 
Menu, 297 

Menu_generate, 224, 297 
Menu_.it em, 297 
menu functions, 312 

menu_create ( ) , 206, 312 
menu_create_item () ,216,312 
menu_destroy ( ) , 220, 312 
menu_destroy_with_proc () , 220, 312 
menu_find () , 221, 312 
menu_get ( ) , 206, 312 
menu_return_item ( ) , 313 
menu_return_value ( ) , 313 
menu_set ( ) , 206, 312 
menu_show () , 206, 211, 222, 226, 312 
menu_show_using_fd () , 313 
menu item 

action procedure, 211, 229 
generate procedure, 211 
margins, 212 
table of attributes, 310 
value of, 211 

menu package, 203 thru 233 
menu processing 

display stage, 222 
notification stage, 222 
MEN U_D I SPLAY, 224 
MENU_D I SPLAY_DONE, 224 
Menu_generate, 224, 297 
Menu_item, 297 
MENU_NOT I F Y, 224 
MENU_NOT I FY_DONE, 224 
menu_prompt ( ) , 439 
message panel item, 145, 154 
META events, 76 
META_SHIFT_MASK, 86, 87 
mouse 

event codes for mouse buttons, 76 
setting position of mouse cursor, 81 
tracking, 76 

mpr_static ( ) , 209, 242 
MS_LEFT, 76 
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MS_MIDDLE, 76 
MS_RIGHT, 76 

multiple views in text subwindows, 135 

N 

namespaces reserved by SunView, 24 
Notifier 

asynchronous signal notification, 267 
base event handler, 270 
child process control events, 262 
client handle, 261 

converting existing programs to use the Notifier, 277 
debugging, 280 

discarding the default action, 273 
error handling, 279 
event handler function, 261 
flow of control in Notifier-based programs, 17 
interposing on frame open/close, 271 
interposing on resize events, 273, 389 
interposition, 261 
overview, 15, 261 
pipes, 264 
polling, 269 
prohibited signals, 260 
prohibited system calls, 259 
registering an event handler, 262 
restrictions imposed on clients, 259 
signal events, 265 
table of functions, 314 
when to use, 259 
Notifier functions, 314 

notify_default_wait3 () , 262, 314 
notify_dispatch () , 277, 314 
notify_do_dispatch ( ) , 200, 278, 314 
not if y_dump ( ) , 280 
notify_f lush_jpending ( ) , 314 
notify_interpose_destroy_func (), 273, 314 
notify_interpose_event_func () , 271, 314 
notify_interpose_wait3_func () , 199 
notify_itimer_value () , 259, 270, 314 
notify_next_destroy_func () , 315 
notify_next_event_func () , 271, 315 
notify_no_dispatch () , 278, 315 
notify_perror (), 279, 315 
notify_set_destroy_func () , 260, 315 
notify_set_exception_func () , 260, 315 
notify_set__input_func () , 260, 264, 266, 315 
notify_set_itimer_func () , 259, 268, 269, 270, 315 
notify_set_output_func () , 260, 266, 316 
notify_set_signal_func () , 78, 261, 265, 316 
notify_set_wait3_func () , 260, 262, 316 
notify_start ( ) , 316 
notify_stop (), 278, 316 
notify_veto_destroy () , 274, 316 
notify procedure 
for menu, 210 
for panel button items, 154 
for panel choice items, 159 
for panel slider items, 172 
for panel text items, 168 
for panel toggle items, 163 
notify procs, 16 

NOTIFY_DONE, 262, 263, 264, 269, 274, 276 



notify_errno, 279 

Notify_error, 279 

N OT I F Y_E RROR_ABORT , 280 

NOT IFY_FUNC_NULL, 265, 279 

NOTIFY_IGNORED, 262, 263, 267 

NOTIFY_OK, 279 

NOT I F Y_P OLL I N G_I T I MER, 269 

o 

object 

definition of, 5 
destruction of, 274 
handle, 22 

non-window visual objects, 7 
window objects, 7 
opening a font, 33 

P 

painting panels and panel items, 173 
panel, 139 , 297 

action functions, 178 
attributes, 317 

attributes applying to all item types, 147 

caret, 167 

caret item, 167 

caret manipulation, 168 

creation, 146 

data types, 297 

default event-to-action mapping, 177 

definition of, 145 

event handling mechanism, 177 

interface summary, 317 

item label, 145 

item menu, 145 

iterating over all items in a panel, 176 
modifying attributes, 148 
painting, 173 

panel space vs. window space, 181 
panel -wide item attributes, 150 
positioning items within a panel, 147 
retrieving attributes, 150 
simple panel window example, 3 1 
table of attributes, 317 
table of functions and macros, 324 
table of generic panel item attributes, 318 
using scrollbars with, 152 
panel attribute settings 

PANEL__ALL, 157, 163, 168, 172 
PANEL_CLEAR, 173 
PANEL_CURRENT, 157 
PANEL_DONE, 172 
PANEL_HORI ZONTAL, 148, 166 
PANEL_INVERTED, 159 
PANEL_MARKED, 159 
PANEL_NO_CLEAR, 173 
PANEL_NON_PRINTABLE, 168 
PANEL_NONE, 157, 159, 163, 168, 174 
PANEL_SPECIFIED, 168 
PANEL_VERTI CAL, 148, 157, 166 
panel attributes, 317 

P ANEL_ACCEP T_KEY STROKE, 177, 178, 317, 318 
PANEL BACKGROUND PROC, 177, 178, 317 
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panel attributes, continued 

PANE L_BL I NK_CARET , 151, 317 
PANEL_BUTTON, 147 
PANEL_CARET_ITEM, 149, 167, 317 
PANEL_CHOICE, 147 
PANE L_CHO I CE_F ONT S, 320 
PANE L_CHO I CE_I MAGE, 151, 320 
PANE L_CHO I CE__I MAGES , 157, 320 
PANEL_CHOICE_STRING, 320 
PANEL_CHOICE_STRINGS, 157, 320 
PANEL_CHOICE_X, 320 
PANEL_CHOICE_XS, 157, 320 
PANEL_CHOICE_Y, 320 
PANEL_CHOICE_YS, , 157, 320 
PANE L_CHO I CE S_BOLD, 320 
PANEL_CLIENT_DATA, 176, 318 
PANE L_C Y CLE, 147 

PANE L_D I SPLAY_LEVEL, 157, 163, 320 

PANEL_EVENT_PROC, 177, 179, 317, 318 

PANEL_FEEDBACK, 159, 320 

PANE L_F IRS T_I TEM, 176, 317 

PANEL_ITEM_COLOR, 318 

PANEL_ITEM_RECT, 318 

PANE L_I TEM_X, 147,318 

PANE L_I TEM_X_GAP, 148, 317 

PANE L_I TEM_Y, 147, 318 

PANE L_I TEM_Y_GAP, 148, 317 

PANE L_LABE L_BOLD, 150, 317, 318 

PANEL_LABEL_FONT, 318 

PANE L_LABEL_I MAGE , 154, 318 

PANEL_LABEL_STRING, 154, 318 

PANE L_LABE L_X, 148, 318 

PANE L_LABE L_Y, 148, 318 

PANEL_LAYOUT, 148, 150, 157, 166, 317, 318, 320 

PANE L_MARK_I MAGE, 320 

PANEL_MARK_IMAGES, 157, 321 

PANE L_MARK_X, 321 

PANE L_MARK_XS, 157, 321 

PANE L_MARK_Y, 321 

PANE L_MARK_Y S, 157, 321 

PANEL_MASK_CHAR, 323 

PANE L_MAX_VALUE, 172, 173, 322 

PANEL_MENU_CHOI CE_FONTS, 318 

PANE L_MENU_CHO I CE_I MAGE S , 318 

PANEL_MENU__CHOI CE_STRI NGS, 172, 319 

PANE L_MENU_CHO I CE_VALUE S , 172, 319 

PANE L_MENU_MARK_I MAGE, 165, 321 

PANE L_MEN U_N OMARK_I MAGE, 165, 321 

PANEL_MENU_TITLE_FONT, 319 

PANEL_MENU_TITLE_IMAGE, 319 

PANEL_MENU_TITLE_STRING, 319 

PANE L_ME S SAGE, 147 

PANE L_MI N_VALUE, 172, 173, 322 

PANEL_NEXT_I TEM, 176, 319 

PANE L_NOMARK_I MAGE, 321 

PANE L_N OMARK_I MAGE S , 157, 321 

PANE L_N OT I F Y_LEVE L, 168, 172, 322, 323 

PANEL_NOTIFY_PROC, 154, 159, 168, 319 

PANEL_NOTIFY_STRING, 168, 323 

PANEL_PAINT, 150, 173, 319 

PANEL_PARENT_PANEL, 319 

PANEL_SHOW_I TEM, 151, 167, 319 

PANE L_SH OW_MENU, 150, 317, 319 

PANE L_SHOW_MENU_MARK, 159, 321 



panel attributes, continued 

PANEL_SHOW_RANGE, 172, 322 
PANEL_SHOW_VALUE, 172, 322 
PANEL_SLIDER_WIDTH, 172, 322 
PANEL_TEXT, 147 
P ANEL_T OGGLE, 147 
PANEL_TOGGLE_VALUE, 321 
PANEL_VALUE, 149, 150, 173, 321, 322, 323 
P ANEL_VALUE_D I SP LAY_LEN GTH, 167, 323 
P ANEL_VALUE_F ONT, 322, 323 
PANEL_VALUE_STORED_LENGTH, 167, 323 
PANEL_VALUE_X, 148, 319 
PANEL_VALUE_Y, 148, 319 
panel data types 
Panel, 297 

Panel_attribute, 297 
Panel__item, 297 
Panel_setting, 297 
panel functions and macros, 324 

panel_accept_key () , 179, 324 
panel_accept_menu ( ) , 179, 324 
panel_accept_preview ( ) , 179, 324 
panel_advance_ca ret () , 168, 324 
panel_backup_caret () , 168, 324 
panel_begin_preview () , 179, 324 
panel_button_image () , 155, 324 
panel_cancel_preview () , 179, 324 
panel_create_item ( ) , 33, 147, 324 
panel_default_handle_event () , 178, 325 
panel_destroy_item () , 151, 325 
panel_each_item ( ) , 325 
panel_event () , 182, 325 
panel_get () , 150, 325 
panel_get_value ( ) , 150 
panel_paint ( ) , 173, 325 
panel_set () , 149, 325 
panel_set_value ( ) , 149 
panel_text_notify ( ) , 169, 325 
panel_update_preview () , 179, 326 
panel_update_scrolling_size ( ) , 152, 326 
panel_window_event () , 182, 326 
panel item 

accepting selection, 177 
basic item types, 145 
button item, 145, 154 thru 157 
choice item, 145, 157 thru 163 
choice item “creep”, 148 
creation, 147 

cycle item description, 161 

default positioning, 148 

destroying, 151 

explicit positioning, 147 

item types for creation routine, 147 

layout of components, 148 

message item, 145, 154 

modifying attributes, 148 

painting, 173 

positioning, 147 

previewing selection, 177 

retrieving attributes, 150 

slider item, 146, 172 thru 173 

table of choice and toggle item attributes, 320 

table of slider item attributes, 322 

table of text item attributes, 323 
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panel item, continued 

text item, 146, 166 thru 172 
toggle item, 146, 163 thru 165 
Panel_attribute, 297 
panel_biitton_image memory, 155 
PANEL_CHOICE_FONT, 165 
PANEL_EVENT_CANCEL, 178 
PANE L_E VENT_DRAG__I N , 178 
PANEL_EVENT_MOVE_IN, 178 
PANEL_INSERT, 169 
Panel_item, 297 
PANEL_NEXT, 169 
PANEL_NONE, 169 
PANEL_PREVIOUS, 169 
Panel_setting, 297 
performance hints — locking and batching, 96 
perror(3), 279 
pipes, 264 
pixels, 91 
pixrect, 91 
pixwin, 89 

background color, 103 
batching, 97, 98 
bitplane control, 109 
cgf our frame buffer, 113 
changing region size, 100 
clipping in a pixwin, 100 
clipping with regions, 100 
colormap, 106 
colormap manipulation, 101 
colormap name, 106 
destruction, 101 
determining region size, 100 
foreground color, 103 
interface summary, 327 
inverting colors, 107 
locking, 96, 97 

locking and batching interaction, 100 

performance hints, 97, 98 

plane groups, 113 

positioning, 45 

rasterop function, 92 

regions, 100 

rendering speed, 96 

retained regions, 100 

table of color manipulation functions, 331 

table of drawing functions, 327 

what is a pixwin?, 91 

write routines, 92 

writing text, 94 

pixwin functions and macros, 327 

pw_use_fast_monochrome (), 114 
pw_batch ( ) , 99 
pw_batch_of f ( ) , 99, 327 
pw_batch_on ( ) , 99, 327 
pw_batchrop () , 94, 327 
pw_blackonwhite () , 107, 331 
pw_char () , 93, 327 
pw_close () , 101, 327 
pw_copy () , 96, 327 
pw_cyclecolormap () , 106, 331 
pw_dbl_access (), 112,331 



pixwin functions and macros, continued 
pw_dbl_f lip () , 112, 331 
pw_dbl_get ( ) , 113, 331 
pw_dbl_release () , 112, 331 
pw_dbl_set ( ) , 112, 331 
pw_get ( ) , 96, 327 
pw_get_region_rect () , 100, 327 
pw_getattributes () , 109, 331 
pw_getcmsname (), 106, 331 
pw_getcolormap () , 106, 331 
pw_getdefau Items () , 332 
pw_line () , 95, 328 
pw_lock () , 97, 328 

PW _ 0P _ C0UNT ’ 99 
pw_pf sysclose (), 94, 328 
pw_pf sysopen ( ) , 94, 328 
pw_polygon_2 ( ) , 95, 328 
pw_polyline () , 95, 328 
pw_polypoint ( ) , 93, 328 
pw_put ( ) , 92, 328 
pw_putatt r ibut e s () , 109, 332 
pw_putcolormap ( ) , 106, 1 10, 332 
pw_read () , 96, 329 
pw_region () , 100, 329 
pw_replrop ( ) , 93, 329 
pw_reset ( ) , 98, 329 
pw__reversevideo ( ) , 107, 332 
pw_rop ( ) , 92, 329 
pw_set_region_rect () , 100, 329 
pw_setcmsname (), 106, 332 
pw_show ( ) , 99, 329 
pw_stencil ( ) , 94, 329 
pw_text () , 94, 330 
pw_traprop ( ) , 95, 330 
pw_ttext ( ) , 94, 330 
pw_unlock () , 97, 330 
pw__vector () , 93, 330 
pw_whiteonblack ( ) , 107, 332 
pw_write ( ) , 92, 330 
pw_writebackground {) , 92, 330 
text routines, 93 
polling, 269 

pop-up windows, 12, 36 thru 42 
blocking, 40 
example program, 359 
non-blocking, 38 
restrictions, 42 

porting programs to SunView, 277 

SunWindows-based, 433, see converting programs to Sun- 
View 

programmatic scrolling, 253 
pty (pseudo-tty), 50 
pw_batch, 99, 327 

R 

reading events, 87 
Rect struct, 45 

refusing the keyboard input focus, 78 
regions of a pixwin, 100 

registering an event handler with the Notifier, 262 
releasing the event lock, 87 
rendering speed, 96 
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reserved namespaces, 24 scrollbar data types, continued 

restrictions on use of UNIX facilities by SunView applications, 259 Scrollbar_attribute_value, 297 

row/column space in a window, 46 Scrollbar_setting, 297 

example program, 374 scrollbar functions, 336 

scrollbar clear bubbled, 336 



s 

sample programs, see example programs 
Scroll_motion, 297 
scrollbar, 245, 297 
basic usage, 250 
model, 247 

programmatic scrolling, 253 
SCROLLBAR default symbol, 250 
table of attributes, 333 
table of functions, 336 
thumbing, 249 
use with canvases, 57 
use with panels, 152 
user interface, 249 
scrollbar attributes, 333 

SCROLL_ABSOLUTE_CURSOR, 333 
SCROLL_ACTIVE_CURSOR, 333 
SCROLL_ADVANCED_MODE, 333 
SCROLL_BACKWARD_CURSOR, 333 
SCROLL_BAR_COLOR, 333 
SCROLL_BAR_D I SPLAY_LEVEL, 333 
SCROLL_BORDER, 333 
SCROLL_BUBBLE_COLOR, 333 
SCROLL_BUBBLE_D I SPLAY_LEVEL, 333 
SCROLL_BUBBLE_MARGIN, 333 
SCROLL_DIRECTION, 251, 333 
SCROLL_END_P 01 NT_AREA, 333 
S CR0LL_F ORWARD_CURS OR, 333 
SCROLL_GAP, 333 
SCR0LL_HEI GHT, 250, 334 
SCROLL_LAST_VIEW_START, 253, 334 
SCROLL_LEFT, 334 
SCROLL_LINE_HEIGHT, 334 
SCROLL_MARGIN, 334 
SCROLL_MARK, 334 
SCROLL_NORMALIZE, 253, 334 
SCROLL_NOTIFY_CLIENT, 334 
SCROLL_OBJECT, 334 
SCROLL_OB JECT_LEN GTH, 247, 334 
SCROLL_PAGE_BUTTON_LENGTH, 334 
SCROLL_PAGE_BUTTONS, 334 
SCROLL_P AI NT_BUTT ON S_P ROC, 334 
SCROLL_P IXWIN, 334 
SCROLL_P LACEMENT, 250, 334 
SCROLL_RECT, 250, 334 
SCROLL_REPEAT_TIME, 335 
SCROLL_REQUEST_MOTI ON, 335 
SCROLL_REQUEST_OFFSET, 335 
SCROLL_THI CKNESS, 250, 251, 335 
SCROLL_TO_GRID, 335 
SCROLL_TOP, 335 
SCROLL_VIEW_LENGTH, 247, 335 
SCROLL_VIEW_START, 247, 253, 335 
SCROLL_WIDTH, 250, 335 
scrollbar data types 

Scroll_motion, 297 
Scrollbar, 297 
Scrollbar_attribute, 297 



scrollbar_create () , 152, 250, 336 
scrollbar_destroy { ) , 250 
scrollbar_get () , 250 
scrollbar_paint ( ) , 336 
scrollbar_paint_bubble ( ) , 336 
scrollbar_j)aint_clear ( ) , 336 
scrollbar_scroll_to () , 253, 336 
scrollbar_set () , 250, 336 
Scrollbar_attribute, 297 
Scrollbar_attribute_value, 297 
Scrollbar_setting, 297 
selection of panel items 
buttons, 154 
choices, 158 
sliders, 172 
text, 167 
toggles, 163 
Selection Service, 255 
setting position of mouse cursor, 81 
Setting the contents of a Text Subwindow 
Setting contents, 128 
SHIFT_CAP SLOCK, 79 
SHIFT_CTRL, 79 
SHIFT_LEFT, 79 
SHIFT_LOCK, 79 
SHIFT_META 79 
SHIFT_RIGHT, 79 
SHIFTMASK, 86, 87 
show color, 104 
SIGALRM, 260 
sigblock(2), 267 
SIGCHLD, 260 
SIGCONT, 259 
SIGIO, 260 
signal(3), 259, 265 

Notifier-compatible version, 265 
signals — use with Notifier, 265 
SIGPIPE, 266 
SIGTERM, 260 
SIGURG, 78, 260 
sigvec(2), 259 
SIGVTALRM, 260 
slider panel item, 146, 172 thru 173 
stop key, 78 
subframe, 12 
subwindow layout 

discussion of image browser 1 program, 43 
example program, 370 
subwindows, 12 

changing layout dynamically, 45 
definition of, 15 
specifying layout, 44, 45 
specifying size, 43 
SunOS 4.1, 3 
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<suntool/icon. h>, 241 
<suntool /menu . h>, 203 
<suntool/panel .h>, 139 
<suntool/ scrollbar .h>, 152, 245 
<suntool/seln.h>, 255 
<suntool/ sunview . h>, 21 
<suntool/textsw.h>, 117 
<suntool/tty -h>, 195 
SunView 

changes in SunOS releases, 2 

code no longer supported, 3 

converting programs from S unWindows, 433 

data types, 294 

file descriptor limits, 50 

frame header, 14 

graphics standards in windows, 1 

history, 2 

interface outline, 21 
interface summary, 285 
libraries, 21 
model, 5 
objects, 5 
overview, 1 
plane groups, 115 
porting programs to, 277 
reserved namespaces, 24 

restrictions on use of UNIX facilities by applications, 259 
source code of programs, 359 
standard functions for objects, 23 
summary of object types, 7 
SunView 1 .80 Update, xxvii, 3 
<sunwindow/cnis_mono .h>, 103 
<sunwindow/ rect . h>, 45 
<sunwindow/win_cursor .h>, 234 
SunWindows 

converting programs to SunView, 433 
equivalent code in SunView, Table C-l 
system(3), 260 

system calls not to be used under SunView, 259 

T 

terminal emulator sub window — see “tty subwindow”, 195 
text notification procedure 
default, 169 

possible return values, 169 
text panel item, 146, 166 thru 172 
text subwindow, 117 

as a sequence of characters, 120 

attribute ordering, 120 

checking its status, 121 

concepts, 120 

creation, 120 

discarding edits, 127 

edit log, 126 

editing contents of, 124 

and the file system, 126 

finding text, 132 

getting a text selection, 120 

insertion point, 120, 123, 124, 125 

interface summary, 337 

manipulating the backing store, 124 

marking text, 133 
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matching a span of characters, 132 
matching a specific pattern, 132 
multiple views, 135 
notification, 136 
overflow of edit log, 126 
positioning the caret, 123 
positioning the text, 129 
reading from, 123 
saving edits, 127 
setting selection, 135 
storing edits, 127 
table of attributes, 337 
table of functions, 343 

table of Textsw_action attributes, 137, 341 
table of Textsw_status values, 122, 342 
writing to, 122 

text subwindow attributes, 337 

TEXTSW_ADJUST_IS_PENDING_DELETE,337 
TEXTSW_AGAIN_RECORDING, 337 
TEXTSW_AUTO_INDENT, 337 
TEXTSW_AUTO_SCROLL_BY, 337 
TEXTSW_BLINK_CARET, 337 
TEXTSW_BROW S I NG, 337 
TEXTSW_CHECKPOINT_FREQUENCY, 337 
TEXTSW_CLIENT_DATA, 337 
TEXTSW_CONFIRM_OVERWRITE, 337 
TEXTSW_CONTENTS, 123, 127, 337 
TEXTSW_CONTROL_CHARS_USE_FONT, 337 
TEXTSW_DISABLE_CD, 337 
TEXTSW_D I SABLE_LOAD, 338 
TEXTSW_EDIT_COUNT, 338 
TEXTSW_F I LE, 38, 121, 338 
TEXTSW_FILE_CONTENTS, 338 
TEXTSW_FIRST, 121, 130, 338 
TEXTSW_FIRST_LINE, 130, 338 
TEXTSW_HISTORY_LIMIT, 338 
TEXTSW_IGNORE_LIMIT, 338 
TEXTSW_INSERT_FROM_FILE, 338 
TEXTSW_I N SERT_MAKE S_VI S IBLE, 338 
TEXTSW_I NSERT I ON_P 0 1 NT, 123, 338 
TEXTSW_LEFT_MARGIN, 338 
TEXTSW_LENGTH, 120, 338 
TEXTSW_L I NE_BRE AK_ACT I ON, 338 
TEXTSW_LOWER_CONTEXT, 338 
TEXTSW_MARK_DEFAULTS, 133 
TEXTSW_MARK_MOVE_AT_I NSERT, 133 
TEXTSW_MEMORY_MAX I MUM, 126, 339 
TEXTSW_MENU, 339 
TEXTSW_MOD I F I ED, 121, 339 
TEXTSW_MULTI_CLICK_SPACE, 339 
TEXTSW_MULT I_CLI CK_T I MEOUT, 339 
TEXTSW_NOTIFY_PROC, 136, 339 
TEXTSW_READ_ONLY, 339 
TEXTSW_SCROLLBAR, 339 
TEXTSW_STATUS, 120, 121, 339 
TEXTSW_STORE_CHANGES_FILE, 339 
TEXTSW_STORE_SELF_IS_SAVE, 339 
TEXTSW_UPDATE_SCROLLBAR, 340 
TEXTSW_UPPER_CONTEXT, 340 

text subwindow constants 

TEXTSW_INFINITY, 123, 124, 125 
TEXTSW_UNIT_IS_CHAR, 124 
TEXTSW_UNIT_IS_LINE, 124 
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text subwindow data types 
Textsw, 297 

Textsw_index, 120, 297 
Textsw_status, 121, 297 
text subwindow functions, 343 

textsw_add_mark () , 133, 343 
textsw_append_file_name () , 126, 343 
textsw_delete () , 124, 343 
textsw_edit ( ) , 124, 343 
textsw_erase () , 124, 343 
textsw_file_lines_visible () , 131, 343 
textsw_f ind_bytes () , 132, 343 
textsw_f ind_mark { ) , 134, 344 
textsw_f irst ( ) , 135, 344 
textsw_index_for_f ile_line () , 130, 344 
textsw_insert (), 122, 344 
textsw_rnatch_bytes { ) , 132, 344 
textsw_next ( ) , 135, 344 
textsw_normalize_view () , 131,344 
textsw_possibly_normalize () , 131, 344 
textsw_remove_mark ( ) , 134, 345 
textsw_replace_bytes () , 125, 345 
textsw_reset (), 127, 138, 345 
textsw_save (), 127, 138, 345 
textsw_screen_line_count () , 131, 345 
textsw_scroll_lines (), 130, 345 
textsw_set_selection () , 135, 345 
textsw_store () , 138 
textsw_store_f ile () , 127, 346 
Textsw, 297 
Text sw_act ion, 136 
Textsw_action attributes, 341, 137 

TEXTSW_ACTION_CAPS_LOCK, 137, 341 
TEXTSW_ACTION_CHANGED_DIRECTORY, 137, 341 
TEXT SW_ACT I ON_ED I TED_F I LE, 137, 341 
TEXTSW_ACTION_FILE_IS_READONLY, 137, 341 
TEXTSW_ACT I ON_LOADE D_F I LE, 137, 341 
TEXTSW_ACT I ON_ED I TED_F I LE, 138 
TEXTSW_ACT I ON_LOADE D_F I LE, 138 
TEXTSW_ACTION_TOOL_CLOSE, 137, 341 
TEXTSW_ACTION_TOOL_DESTROY, 137, 341 
TEXT SW_ACT I ON_TOOL_MGR, 137, 341 
TEXTSW_ACTION_TOOL_QUIT, 137, 341 
TEXT SW_ACT I ON_U S I NG_MEMORY, 137, 341 
Textsw_index, 120, 297 
TEXT SW_I NF I N I T Y, 123, 124, 125 
Textsw_status, 121, 297 
Textsw_status values, 342, 122 

TEXTSW_STATUS_BAD_ATTR, 122, 342 
TEXT SW_ST ATUS_BAD_ATTR_VALUE, 122, 342 
TEXTSW_STATUS_CANNOT_ALLOCATE, 122, 342 
TEXTSW_STATU S_CANNOT_I NSERT_FROM_F ILE, 122, 
342 

TEXT SW_ST ATU S_CANNOT_OPEN__I NP UT, 122, 342 
TEXTSW_STATUS_OKAY, 122, 342 
TEXTSW_STATUS_OTHER_ERROR, 122, 342 
TEXTSW_STATUS_OUT_OF_MEMORY, 122, 342 
TEXT SW_UN I T_I S_CH AR, 124 
TEXT SW_UN I T_I S_LI NE , 124 
TEXTS W_WRAPAROUND_SIZE, 126 
timeout events, 268 
toggle panel item, 146, 163 thru 165 



translating events from canvas space to window space, 63, 88 
translating events from panel space to window space, 181 
tty subwindow 
creating, 197 

differences with Sun console, 198 
example program, 379 
example program to list files, 34 
file descriptor, 199 
input/output to tty subwindow, 197 
interface summary, 347 
monitoring, 199 
overview, 195 
reading and writing, 199 
special escape sequences, 199 
standard escape sequences, 198 
table of functions, 347 
table of special escape sequences, 349 
tty subwindow attribute values 

T T Y_ARGV_DO_N OT_FORK, 347 

tty subwindow attributes 

TTY_ARGV, 197, 199, 200, 347 
TTY_CONSOLE, 347 
TTY_PAGE_MODE, 347 
TTY_PID, 199 

TTY_QUIT_ON_CHILD_DEATH, 347 
TTY_TTY_FD, 199, 347 
tty subwindow functions, 347 
example program, 379 
tty sw_input ( ) , 34, 197, 347 
ttysw_output (), 198, 347 

u 

UNIX system calls and SunView 
alarm(3), 259 
f cntl(2), 260, 264 
f ree(3), 283 
getitimer(2), 259 
I/O in a tty subwindow, 199 
ioctl(2), 260 
perror(3), 279 
sigblock(2), 267 
signal(3), 259, 265 
sigvec(2), 259 
system calls not to be used, 259 
wait(2), 260 
wait3(2), 259, 262 
Update, SunView 1.80, xxvii 

V 

views in text subwindows, 135 
Virtual User Input Device ( VUID ), 70 
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wait(2), 260 
wait 3(2), 259, 262 
WIN_ASCII_EVENTS, 80, 304 
W IN_EXTEND_TO_EDGE, 43, 44 
WIN_IN_TRANSIT_EVENTS, 80, 304 
WIN_LEFT_KEYS, 80, 304 
WIN_MOUSE_BUTTONS, 80, 304 
WIN_NO_EVENTS, 80, 304 
WIN REPAINT, 77 
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WIN_RESIZE, 77 
WIN_RIGHT_KEYS, 80, 304 
WIN_STOP, 78 
WIN_TOP_KEYS, 80, 304 
WIN_UP_ASCII_EVENTS, 80, 304 
WIN_UP_EVENTS, 80, 304 
window, 25 

classes of windows, 12 
creation, 27 
destruction, 28 

initiating event processing, 27 
interface summary, 351 
limit to number of windows, 50 
simplest SunView program, 29 
table of attributes, 351 
table of functions and macros, 356 
table of input-related window attributes, 305 
window attributes, 351 
WIN_ALARM, 351 
WIN_BELOW, 351 
WIN_BOTTOM_MARGIN, 46, 351 
WIN_CLIENT_DATA, 351 
WIN_COLUMN_GAP, 46, 351 
WIN__COLUMN_WI DTH, 46, 351 
WIN_COLUMNS, 43, 146, 351 
WIN_CONSUME_KBD_EVENT, 63, 351 
W I N_CON SUME_KB D_E VENT S , 351 
WIN_CONSUME_PICK_EVENT, 351 
WIN_CONSUME_PICK_EVENTS, 351 
WIN_CURSOR, 236, 237, 351 
WIN_DEVICE_NAME, 351 
WI N_DEV I CE_NUMBER, 35 1 
WIN_ERROR_MSG, 33, 351 
WIN_EVENT_PROC, 63, 71, 351 
W I N_E VE NT_S TATE, 86, 351 
WIN_FD, 351 

WIN_FIT_HEIGHT, 33, 352 
WIN_FIT_WIDTH, 33, 352 
WIN_FONT, 33, 147, 281, 352 
WIN_GRAB_ALL_INPUT, 82, 352 
WIN_HEIGHT, 146, 352 

WI N_HORI Z ONTAL_SCROLLBAR, 152, 245, 352 

WI N_I GNORE_KBD_EVENT, 352 

W I N_I GN ORE_KBD_E VEN T S, 352 

WIN_IGNORE_PICK_EVENT, 352 

WIN_IGNORE_PICK_EVENTS, 352 

W I N_I NP UT_DE S I GNE E, 82, 352 

WIN_KBD_FOCUS, 352 

WI N_KBD_I NPUT_MASK, 352 

W I N_KE YBOARD_F OCU S, 81 

WIN_LEFT_MARGIN, 46, 352 

WIN_MENU, 352 

WIN_MOUSE_XY, 81, 352 

WIN_NAME, 352 

WIN_OWNER, 352 

WIN_PERCENT_HE IGHT, 353 

WI N_PERCENT_WI DTH, 353 

WIN_PICK_INPUT_MASK, 353 

WIN_PIXWIN, 58, 91, 353 

WIN_RECT, 45, 353 

WIN_RIGHT_MARGIN, 46, 353 

W I N_R I GHT_0F, 353 

W I N_R0W__GAP, 46, 353 
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WIN_ROWS, 43, 146, 353 
WIN_SCREEN_RECT, 353 
WIN_SHOW, 38, 353 
WIN_TOP_MARGIN, 46, 353 
WIN_TYPE, 353 

WIN_VERT ICAL_SCROLLBAR, 152, 245, 353 
WIN_WIDTH, 146, 353 
WIN_X, 45, 353 
WIN_Y, 45, 353 
window classes 

base frame, 12 
frame, 12 
pop-up, 12 
subframe, 12 
subwindow, 12 

window functions and macros, 356 
window_bell () , 356 
window_create () , 27, 55, 271, 356 
window_def ault_event_proc 0,71, 356 
window_destroy (),28, 356 
window_done () , 28, 356 
window_f it ( ) , 356 
window_f it_height ( ) , 33, 
window_f it_width () , 33, 356 
window_get ( ) , 27, 356 
window_loop ( ) , 41, 357 
window_main_loop () , 27, 277, 357 
window_read_event () , 64, 87, 181, 357 
window_refuse_kbd_focus () , 78, 357 
window_release_event_lock; ( ) , 87, 357 
window_return 0,41, 357 
window_set ( ) , 27, 148, 357 
window_retum, 51 
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